home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
basic
/
dialogic.zip
/
DIALOGIC.DOC
< prev
next >
Wrap
Text File
|
1990-01-31
|
212KB
|
6,588 lines
January 30, 1990
====================================
Important note to BBS-version users:
====================================
This is the actual DiaLogic product documentation. It has been presented
in its entirety and is supplemented by the accompanying README file, which
should be read before this document. Please realize that references to
DIALOGIC.BAS and DIALOGIC.LIB are intended for the registered copy of
DiaLogic. These files are not present in the BBS version.
Further, some aspects of the document are formatted very differently from
the printed version simply because this manuscript has been converted from
a desktop publishing version to an ASCII format. We wanted to provide you
with complete documentation to DiaLogic, and we sincerely apologize for any
loss in readability.
*
Dialog Software
Box 9889 at 1101 Wilson Boulevard
Arlington, Virginia 22209-0889
(703) 528-1505
LICENSE AGREEMENT
Dialog Software grants a license to use the enclosed software and printed
documentation to the original purchaser. Copies may be made for back-up
purposes only. Copies made for any other purpose are expressly
prohibited, and adherence to this requirement is the sole responsibility
of the purchaser. However, the purchaser does retain the right to sell
or distribute programs that contain DiaLogic routines, so long as the
primary purpose of the included routines is to augment the software being
sold or distributed. Source code for any component of the DiaLogic
program may not be distributed under any circumstances. This license may
be transferred to a third party only if all existing copies of the
software and documentation are also transferred.
WARRANTY INFORMATION
Dialog Software warrants that this product will perform as advertised.
In the event that it does not meet the terms of this warranty, and only
in that event, Dialog Software will replace the product or refund the
amount paid, if notified within 30 days of purchase. Proof of purchase
must be returned with the product, as well as a brief description of how
it fails to meet the advertised claims.
DIALOG SOFTWARE'S LIABILITY IS LIMITED TO THE PURCHASE PRICE. Under no
circumstances shall Dialog Software or the authors of this product be
liable for any incidental or consequential damages, nor for any damages
in excess of the original purchase price.
DiaLogic.
Entire contents Copyright 1989 by Jonathan S. Waldman, Ethan Winer,
Crescent Software, and Dialog Software. All rights reserved.
No portion of this software or manual may be duplicated in any manner
without the written permission of Jonathan S. Waldman or Dialog Software.
QuickBASIC is a trademark of Microsoft Corp.
Dialog Software
Box 9889
1101 Wilson Boulevard
Arlington, Virginia 22209
(703) 528-1505
DiaLogic
Written By Jonathan S. Waldman
Dedicated to my mother and father,
for having started my adventure into computers.
A special thanks, with love, to Donna LeMaitre.
Also, to Microsoft, Stephanie, Nancy, Ethan Winer:
Thanks for your support!
DiaLogic
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Thanks! . . . . . . . . . . . . . . . . . . . . . . . . . . iii
Registration & Upgrades . . . . . . . . . . . . . . . . . . iii
DiaLogic at a Glance . . . . . . . . . . . . . . . . . . . . . . . iv
A Standard . . . . . . . . . . . . . . . . . . . . . . . . . iv
Sophisticated, Elegant, & Powerful . . . . . . . . . . . . . iv
Practical . . . . . . . . . . . . . . . . . . . . . . . . . . v
Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . vi
System . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
QuickBASIC . . . . . . . . . . . . . . . . . . . . . . . . . vi
Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . vi
Intended Audience . . . . . . . . . . . . . . . . . . . . . . vi
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Notational Conventions . . . . . . . . . . . . . . . . . . viii
Technical Support . . . . . . . . . . . . . . . . . . . . . . . xi
PART I: GETTING STARTED . . . . . . . . . . . . . . . . . . . . . . . 1
Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Things To Do First . . . . . . . . . . . . . . . . . . . . . . . . 3
The Demo . . . . . . . . . . . . . . . . . . . . . . . . . . 3
README . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
What's On The Diskette . . . . . . . . . . . . . . . . . . . 4
Copying and Backing Up . . . . . . . . . . . . . . . . . . . 5
Loading the Source Code . . . . . . . . . . . . . . . . . . . 5
PART II: DIALOG BOX BASICS . . . . . . . . . . . . . . . . . . . . . 7
Overview of DiaLogic's Operation . . . . . . . . . . . . . . . . . 9
Arguments in the Call . . . . . . . . . . . . . . . . . . . . 9
The Use of Ambiguous Variable Names . . . . . . . . . . . . . 10
Terms & Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 13
The Elements . . . . . . . . . . . . . . . . . . . . . . . . 13
The Input Focus . . . . . . . . . . . . . . . . . . . . . . . 14
Alt-keys . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The Tilde (~) Character . . . . . . . . . . . . . . . . . . . 15
The DB() Array . . . . . . . . . . . . . . . . . . . . . . . 17
The LB() Array . . . . . . . . . . . . . . . . . . . . . . . 19
The Dialog Box Template . . . . . . . . . . . . . . . . . . . 21
Include Files . . . . . . . . . . . . . . . . . . . . . . . . 22
Table of Contents
DB() Variable Values . . . . . . . . . . . . . . . . . . . . . . . 24
Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Default Values . . . . . . . . . . . . . . . . . . . . . . . 27
Understanding the Elements . . . . . . . . . . . . . . . . . . . . 27
The Window . . . . . . . . . . . . . . . . . . . . . . . . . 28
Text Box . . . . . . . . . . . . . . . . . . . . . . . . . . 31
List Box . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Check Box . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Option Buttons . . . . . . . . . . . . . . . . . . . . . . . 44
Smart Labels . . . . . . . . . . . . . . . . . . . . . . . . 47
Command Buttons . . . . . . . . . . . . . . . . . . . . . . . 50
Group Box . . . . . . . . . . . . . . . . . . . . . . . . . . 53
PART III: CREATING A TEMPLATE . . . . . . . . . . . . . . . . . . . . 55
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A Detailed Example . . . . . . . . . . . . . . . . . . . . . . . . 57
Making a Sketch . . . . . . . . . . . . . . . . . . . . . . . 58
Determining the Sequence . . . . . . . . . . . . . . . . . . 59
Copying & Pasting . . . . . . . . . . . . . . . . . . . . . . 60
Making the Assignments . . . . . . . . . . . . . . . . . . . 63
PART IV: GENERATING A DIALOG BOX . . . . . . . . . . . . . . . . . . 71
Preparing for the Call . . . . . . . . . . . . . . . . . . . . . . 73
Including DIALOGIC.BI . . . . . . . . . . . . . . . . . . . . 74
Initializing the Mouse . . . . . . . . . . . . . . . . . . . 74
REDIMing DiaLogic's Arrays . . . . . . . . . . . . . . . . . 77
Setting the Level . . . . . . . . . . . . . . . . . . . . . . 78
Including the Dialog Box Template . . . . . . . . . . . . . . 80
Setting the Action . . . . . . . . . . . . . . . . . . . . . 81
Setting the Focus . . . . . . . . . . . . . . . . . . . . . . 83
Ky$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Making the Call . . . . . . . . . . . . . . . . . . . . . . . . . 84
Processing the Call . . . . . . . . . . . . . . . . . . . . . . . 85
PART V: CREATING STANDALONE PROGRAMS . . . . . . . . . . . . . . . . 92
Compiling DiaLogic . . . . . . . . . . . . . . . . . . . . . . . . 94
Linking with DiaLogic . . . . . . . . . . . . . . . . . . . . . . 94
Adding to the DIALOGIC Quick Library . . . . . . . . . . . . . . . 96
DiaLogic
PART VI: ADVANCED TOPICS . . . . . . . . . . . . . . . . . . . . . 99
Choosing a Dialog Box Type . . . . . . . . . . . . . . . . . . . 102
Single-Tasking Dialog Boxes . . . . . . . . . . . . . . . . . . 103
Multi-Tasking Dialog Boxes . . . . . . . . . . . . . . . . . . . 107
Stacked Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . 109
Overview . . . . . . . . . . . . . . . . . . . . . . . . . 109
Single-Tasking Stacked Dialog Boxes . . . . . . . . . . . . 111
Multi-Tasking Stacked Dialog Boxes . . . . . . . . . . . . 112
APPENDICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DIALOG BOX ELEMENTS . . . . . . . . . . . . . . . . . . . . . . A-1
MODIFYING DIALOGIC.BAS . . . . . . . . . . . . . . . . . . . . . B-1
TROUBLESHOOTING . . . . . . . . . . . . . . . . . . . . . . . . C-1
Dialog SOFTWARE COLOR CHART . . . . . . . . . . . . . . . . . . D-1
ASCII CHARACTER CHARTS . . . . . . . . . . . . . . . . . . . . . E-1
DiaLogic
Version 1.4E
January 31, 1990
THE
INTRODUCTION
Introduction
Welcome
We have put every effort into making this the finest and most powerful
dialog box program available. We sincerely hope that you love it. If
you have a comment, a complaint, or perhaps a suggestion for another
product you would like to see, please let us know. We want to be your
favorite software company.
Registration & Upgrades
Please take a few moments to fill out the enclosed registration card.
Doing this entitles you to free technical support by phone, as well as
insuring that you are notified of possible upgrades and new products.
Many upgrades are offered at little or no cost, but we cannot tell you
about them unless we know who you are!
Also, please mark the product serial number on your disk labels. License
agreements and registration forms have an irritating way of becoming
lost. Writing the serial number on the diskette will keep it handy.
You may also want to note the version number in a convenient location,
since it is stored directly on the distribution disk in the volume label.
If you ever have occasion to call us for assistance, we will probably
need to know the version number you are using. To determine the version
number please look at the first page of the DiaLogic.BAS source code.
iii
DiaLogic
We are constantly improving all of our products, so you may want to call
periodically to ask for the current version number. Major upgrades are
always announced, however minor fixes or additions generally are not. If
you are having any problems at all, even if you are sure it is not with
one of our products, please call or write to us.
DiaLogic at a Glance
A Standard
DiaLogic gives the professional and hobbyist programmer the ability to
develop programs which have the same standardized interface which has
become a sensation in the computer industry. This interface consists
largely of the dialog box: an intuitive and aesthetic means of gathering
input from a user. Dialog boxes are used in professional, user-friendly
software, and are present in MacIntosh software, Microsoft Windows ,
Hewlett-Packard's New Wave , the OS/2 Presentation Manager , and even in
the DOS 4.0 Shell .
Sophisticated, Elegant, & Powerful
DiaLogic is a sophisticated programming tool which allows you to create
aesthetic text-based dialog boxes with a truly elegant mouse interface.
Generating a dialog box consists of these three steps:
(1) Creating a dialog box definition file called a template
using the generic template we provide.
(2) Initializing a few variables.
(3) Calling the DiaLogic subprogram.
Variations on how DiaLogic is called from a program provides the added
power needed to create any kind of dialog box you could imagine: from a
simple error message with a single ``OK'' button to a full-blown setup
screen which operates in a polled mode! To illustrate this flexibility
iv
Introduction
we have written a demonstration program which displays and explains
dialog boxes as it runs. This program appears on your distribution
diskette as DEMO.BAS.
Practical
DiaLogic's dialog boxes will work and function very much like those you
have possibly used in Microsoft's QuickBASIC version 4.5, QuickC version
2.0, and Works . The use of dialog boxes in your programs will provide
these immediate practical benefits:
* Complex user-query screens will not have to be tediously
coded by you in BASIC. This will give you more time to
spend on other aspects of your program.
* Your dialog boxes will add an aesthetic and highly-
professional look-and-feel to your own programs which
exactly corresponds to the Microsoft standard interface.
* End users will immediately understand the intuitive dialog
box interface, especially if they are using a mouse.
This manual is meant to make the creation of dialog boxes both easy and
enjoyable.
v
DiaLogic
Compatibility
System
DiaLogic will run on IBM XT, AT, and PS/2-class machines and compatibles,
although you will notice better performance on 16mhz or higher. DOS 2.0
or above is needed. We recommend 640K of conventional memory to allow a
sufficient work space while in the QuickBASIC editor.
QuickBASIC
DiaLogic is available for users of QuickBASIC, version 4.x. If you own
an earlier version we suggest that you contact Microsoft for an upgrade.
The current release of QuickBASIC, version 4.5, provides many
improvements over prior versions. Although DiaLogic is fully compatible
with version 4.0, we have used version 4.5 during development and refer
to some of its features throughout this manual. One further note is that
some version-4.5 pull-down menu choices, although functionally identical,
have names which are slightly different from their 4.0 predecessors. We
will be happy to help you if you need more information before trading up.
Using This Manual
Intended Audience
This manual assumes very little knowledge of dialog boxes but a
comfortable understanding of QuickBASIC. We have not attempted to
unnecessarily duplicate information which is QuickBASIC-related and
appears in the QuickBASIC documentation. We do, however, provide many
useful tips.
Contents
This manual follows a progression from general terms and concepts to
specific applications. Therefore, we recommend reading the entire manual
at least once. Here's a summary of this manual's contents:
vi
Introduction
* Part I explains how to install the program and how to make
it available from within the QuickBASIC editor (the
environment).
* Part II presents an operational overview of the product and
provides detailed information about all dialog box-related
terms and concepts.
* Part III contains information about creating dialog box
templates -- special files which contain information needed
to define a dialog box. We present this discussion in a
tutorial-like style since constructing such templates is the
most difficult part of DiaLogic.
* Part IV explains how to call DiaLogic and explains all the
required prerequisite steps.
* Part V explains compiling and linking and provides all the
required steps for creating stand-alone .EXE files which
contain dialog boxes.
* Part VI addresses more advanced features and topics of
DiaLogic such as multi-tasking and stacked dialog boxes.
Several example programs are discussed in terms of practical
programming considerations.
* Appendices appear towards the end of this manual, and should
prove very helpful once you begin using the program.
Appendix A summarizes the template structure for each dialog
box element. Appendix B offers ways of reducing the size
and making modifications to the DiaLogic module. Appendix C
is a troubleshooting section which will assist you in case
of difficulty. Appendix D gives a color chart. Appendix E
provides ASCII character charts.
* A Glossary is provided for your convenience.
vii
Notational Conventions
DiaLogic
We have used some variations in type style mainly so that the manual is
more enjoyable to read. The purpose for most type styles is clear (i.e.,
for topic headings, computer text, etc.), however there are a few uses
which may require further explanation:
* All examples of computer input or output are printed in a
fixed-spaced line printer font. For instance, consider the DO
loop below:
'pause for a key press
DO
LOOP UNTIL LEN(INKEY$)
.
.
.
* Notice also the use of vertical ellipses to convey that more
program instructions may follow and the use of BASIC's REM
symbol (') to present comments.
* Variable names embedded in the main text are often printed
in the line printer font when they are mentioned for the
first time in a discussion. For example:
``The variable X% represents an integer. This means
that X% will occupy two bytes of memory.''
* The first ``X%'' above is easily discernable as a variable
name. To enhance readability we will avoid excessive font-
changes (especially to the line printer font) in the main
text.
viii
Introduction
Instances when the computer input or output may vary
(depending on your hardware, software, etc.) are shown in
italics. For example, the QuickBASIC Quick Library support
module will have a slightly different name depending on its
version number. We therefore would refer to such a file as
in the example below:
LINK PROGNAME.OBJ,,BQLB45 /Q
Notice that not only is ``45'' italicized, but also the
program name, which will vary, is italicized.
* In some examples there may be optional features in a syntax.
These features will be shown in square brackets. For
example, the LET statement is optional in QuickBASIC:
[LET ]A = 10
* There are many instances when we will speak of an array,
usually a TYPE array, and leave its array subscripts empty.
For example:
X().Row = 10
* The above example is not a valid array assignment in BASIC
because its subscripts are missing. Rather, a correct
syntax would be something like this:
X(1, 5).Row = 10
* This would assign element (1, 5) of the Row element for the
X() TYPE array to 10. We've omitted subscripts for many
examples because the focus in much of the manual is on the
array assignments and not on the array subscripts. We
explain the correct use of the subscripts in Part III:
Creating a Template and in Part IV: Generating a Dialog Box.
ix
DiaLogic
* Keys on the keyboard are represented in angle brackets. For
example, <F1> is the F1 function key; <Enter> is the Enter
or Return key. This is an accepted convention but in this
document there may be some confusion since the dialog box
element called a command button is similarly represented in
angle brackets. When context does not make the distinction
clear, we have boldfaced the command button name:
``Pressing <Enter> will execute the <OK> command
button.''
* Program lines from an include file are enclosed in double
angle brackets. Consider this portion of a BASIC program:
REDIM DB(2, 20) AS DialogType
REDIM LB(50) AS ListType
'$INCLUDE: 'TEMPLATENAME.DB'
<<DB(Level%, 1).Code = 1>>
<<DB(Level%, 2).Y = 0>>
<<DB(Level%, 3).X = 0>>
.
.
.
* The DB() array assignments above appear in the
TEMPLATENAME.DB include file: they are not explicitly
present in this BASIC program.
* All BASIC key words and all DOS file names are written in
uppercase letters.
x
Introduction
Technical Support
We always welcome your calls. However, before you call for technical
support please check Appendix C: Troubleshooting, to see if your question
is discussed. If the problem persists you may call us at (703) 528-1505,
between 9:00 a.m. and 5:00 p.m. EST, Monday through Friday. Please
gather as much detail as possible about the problem before you call. In
some extenuating circumstances we may ask to examine the particular
dialog box template and calling syntax being used in order to assist you.
xi
DiaLogic
PART I
GETTING STARTED
Getting Started
Quick Start
This manual covers many important topics that you will need to know in
order to use DiaLogic effectively. However, if you are familiar with
BASIC programming and want to be able to create dialog boxes right away,
simply start QuickBASIC by loading both DIALOGIC.BAS and the DIALOGIC.QLB
Quick Library like this:
QB DIALOGIC.BAS /L DIALOGIC.QLB
This syntax assumes both DIALOGIC files are in the current directory.
Once BASIC has started you will be able to create dialog boxes. Although
this is all you need to do please be aware that the calling requirements
of DiaLogic are extensive. Therefore we strongly recommend that you read
this entire manual before using the program.
Things To Do First
The Demo
Before we get started you should first have a solid understanding of what
dialog boxes are and how they function. For this reason we highly
recommend that you run the demo we have supplied on the distribution
diskette. To run the demo, start QuickBASIC and load the DiaLogic Quick
Library like this:
QB /L DIALOGIC
Once QuickBASIC starts you may load the file DEMO.BAS using the File Open
pull-down menu option (you must use the open option in order to load the
demo correctly). Then press <Shift><F5> to start the program.
3
DiaLogic
Although the demo in no way is meant to replace the manual, it does
provide a means for you to actually interact with dialog boxes. We feel
that once you have read and understand the information in the demo you
should be comfortable with dialog box terminology.
README
Additions or changes to this manual will appear in a file called README.
Simply enter the following DOS command to peruse it:
TYPE README
Installation
What's On The Diskette
The following files should be on your distribution diskette:
File Name Description
DEMO.BAS Our demonstration program. Highly-suggested
viewing material!
DIALOGIC.BAS DiaLogic's BASIC source code.
DIALOGIC.QLB Assembler Quick Library for use when loading
DIALOGIC.BAS into the environment.
DIALOGIC.LIB Assembler Library for use when linking.
DIALOGIC.BI BASIC include file which contains DiaLogic's DECLARE
statements and necessary TYPE declarations.
EXAMPLE?.BAS BASIC example programs.
README A text file which, if present, contains update notes
for DiaLogic.
TEMPLATE.DOC DiaLogic's generic dialog box template.
*.DB Dialog box template include files.
4
Getting Started
Copying and Backing Up
Before you start to use the program you should first make a copy of the
original diskette and then work with the copy. We know we didn't have to
tell you this; but reminding you could prevent a very frustrating
situation should your distribution diskette become damaged. For optimum
performance when using DiaLogic we recommend copying the files onto a
fixed disk.
Loading the Source Code
DiaLogic was written in QuickBASIC and uses assembly language routines
when possible to produce the fastest performance and smallest code.
Future releases of DiaLogic will be further optimized and will take even
greater advantage of low-level languages. Since DiaLogic depends on
external assembler routines, you should make them available to
QuickBASIC. We have provided you with a Quick Library called
DIALOGIC.QLB which contains only assembler routines. You may load this
library like this:
QB /L DIALOGIC
DIALOGIC.BAS may now be loaded into the QuickBASIC environment using the
File Load pull-down menu option.
At some point you may wish to compile DIALOGIC and create a Quick Library
which contains DIALOGIC.BAS and the assembler routines on which it
depends. We will discuss this process in Part V: Creating Standalone
Programs.
5
Dialog Box Basics
Overview of DiaLogic's Operation
This manual is organized to provide very detailed instructions
for implementing dialog boxes. We'd like you to get an overview
of how dialog boxes will be used by your programs before we
present the detailed aspects. This should provide you with
additional background information before reading the rest of the
manual.
Arguments in the Call
Five arguments must be passed for every dialog box. We mention
these arguments for overview purposes only:
Argument
Name Description
DB() The dialog box definition
LB() The contents of all list boxes
Focus% The element on which the cursor rests
Action% The manner in which the dialog box is to operate
Ky$ The most recent keystroke captured
The DB() TYPE array contains all information needed to create a
dialog box. The LB() TYPE array stores all list box items for a
single dialog box. The integer Focus% specifies on which dialog
box element the cursor rests. The integer Action% determines the
pre- and post-operative behavior of a dialog box. And, last, the
conventional (variable-length) string Ky$ enables the calling
program to access the most recent keystroke captured by DiaLogic.
9
DiaLogic
To further clarify things, please realize that the DB() array is
used like a set of ``instructions'' which directs how a dialog
box will be displayed. For instance, the DB() array is why a
Search dialog box looks different from a File Load dialog box.
The argument Action% determines how the dialog box will operate.
For example, one type of operation causes full program control to
remain with the dialog box until the user has completed input;
another allows the calling program to regain control before the
dialog box accepts any user input.
After using a dialog box the calling program may determine what
type of input the user has entered by examining portions of the
DB() array which correspond to the item of interest. Each dialog
box element has a one-to-one correspondence to elements defined
in the DB() array. Additional information is available to the
calling program by examining Focus% and Ky$. The LB() array only
provides information to DiaLogic: it does not return any useful
information.
Don't be concerned if the purpose of each argument is not
understood from our brief overview: all will be fully explained.
The Use of Ambiguous Variable Names
In the interest of making the calling syntax as compact as
possible we have made use of a single TYPE array to hold all the
information needed to display a dialog box. Occasionally,
however, we have used a variable in the TYPE definition for a
purpose which does not seem to correspond to its name. The best
way to understand this is to present an example.
10
Dialog Box Basics
Note:
The DrawIt subprogram is fictitious and is used for
discussion purposes only. It is not included with
DiaLogic.
Suppose we want to create a subprogram, called DrawIt, which
either draws a circle or rectangle, and then adds color to the
figure. We could decide to pass all the information needed in a
single user-defined TYPE. Our TYPE declaration may look
something like this:
TYPE GeometricShape
Code = INTEGER '1 = rectangle, 2 = circle
Wide = INTEGER 'width (or diameter)
High = INTEGER 'height
Colr = INTEGER 'inside color
END TYPE
DIM Shape AS GeometricShape
If we wanted to draw a 5X7 rectangle colored blue we may use the
following variables from our user-defined TYPE:
Shape.Code = 1 'for a rectangle
Shape.Wide = 5 'width of the rectangle
Shape.High = 7 'height of the rectangle
Shape.Colr = 1 'inside color of the rectangle
CALL DrawIt(Shape)
11
DiaLogic
This would draw a rectangle which is 5 units across and 7 units
high. Now, let's say we want to draw a circle. We could use the
following:
Shape.Code = 2 'for a circle
Shape.Wide = 5 'the diameter of the circle
Shape.High = 0 'not used for circles
Shape.Colr = 1 'inside color of the circle
CALL DrawIt(Shape)
Notice that Shape.Wide now refers to a diameter and that
Shape.High is not even used for the circle! If the DrawIt
program is ``smart'' it will inspect Shape.Code to determine
which elements of the Shape TYPE array it should use. In order
to draw the rectangle it would require the width, height, and
color of the object. But to draw the circle, only the ``width''
(i.e., the diameter) and the color are needed. Thus, we've used
Shape.Wide to hold either the rectangle's width or the circle's
diameter.
Our rudimentary example explains how a TYPE variable name can be
called something which is inconsistent with its function. Please
realize that this ambiguity could be avoided by creating an extra
variable in the TYPE called Diam, for the diameter. The TYPE
declaration would then look like this:
TYPE GeometricShape
Code = INTEGER '1 = rectangle, 2 = circle
Wide = INTEGER 'width
High = INTEGER 'height
Diam = INTEGER 'diameter
Colr = INTEGER 'inside color
END TYPE
DIM Shape AS GeometricShape
The addition of Diam is wasteful because it adds 2 bytes (the
size of an integer) to the TYPE definition. Further, 4 bytes are
wasted when a circle is defined since both width (2 bytes) and
height (2 bytes) would not be used.
12
Dialog Box Basics
One solution to such variable naming problems is to use generic
nomenclature. Thus, we could have defined Wide as Across, Size,
or something more general, such as NumberOne. This last example,
NumberOne, is fitting: it not only is generic, but also it
conveys that a number is expected and not a string. When
appropriate we've used similar generic nomenclature for TYPE
variable names which are used for different purposes. In fact we
make use of the names NumberOne and NumberTwo! In a few very
rare instances you may encounter variable names which seem really
inappropriate, but keep in mind that this was done ultimately to
save a few bytes.
You will learn that DiaLogic has a TYPE definition which is more
complex than the one used in our DrawIt example. In fact,
DiaLogic's TYPE arrays are not only larger but also are
dimensioned. A TYPE array is dimensioned using BASIC code
similar to:
DIM Shape(20) AS GeometricShape
If we had done this we could have passed up to 20 pre-defined
shapes in a single call to DrawIt. The ability to pass a very
large amount of information in a single variable is indeed a most
powerful feature of dimensioned TYPE arrays.
Terms & Concepts
Since dialog boxes are associated with several terms which may be
new to you, understanding this section is essential.
The Elements
Dialog boxes are comprised of dialog box elements (DBEs). The
eight DBEs are summarized in Figure 2. You should acquaint
yourself not only with their names but also with their associated
numbers. The numbers are important, for they describe a specific
DBE in terms of a numerical code:
13
DiaLogic
Code Description
1 Window
2 Text Box
3 List Box
4 Check Box
5 Option Buttons
6 Smart Label
7 Command Button
8 Group Box
Beginning on page 27, the section called Understanding the
Elements explains each DBE in much greater detail.
The Input Focus
The DBE on which the cursor rests is said to have the input
focus, and only the DBEs designated with a happy face in Figure 2
may receive it. The input focus is important because it allows a
specific dialog box element, such as a text box, to accept
information from the user.
The input focus is transferred from one DBE to another in several
ways:
* Using the <Tab> or <Shift><Tab> keys: These keys will
access each DBE in a pre-defined Sequence. <Tab> will
access dialog box elements in one direction while
<Shift><Tab> will access them in the opposite direction.
* Using an Alt-key: Alt-keys, explained next, will directly
access a DBE by immediately transferring the input focus.
* Using the mouse: Placing the mouse cursor over a DBE and
pressing a mouse button will transfer the input focus.
This mouse maneuver is commonly referred to as clicking
on an option.
14
Dialog Box Basics
Alt-keys
When the <Alt> key is pressed certain words will suddenly reveal
a highlighted character. This character is referred to as an
Alt-key. To access a DBE which has an Alt-key character, simply
hold down the <Alt> key and type the highlighted character. You
will notice that the input focus is transferred. If there are
different DBEs with the same Alt-key, then each will be accessed
in turn.
Alt-keys provide keyboard users with the ability to directly
access a dialog box element. They may be defined for the letters
``A'' through ``Z'' and the numbers 0 through 9 only.
If the input focus is on a dialog box element other than a text
box or list box then an Alt-key may be pressed unaccompanied by
the <Alt> key. For example, if the input focus is on a check box
and you wish to transfer it to an option button with an Alt-key
F, then you may press either <Alt>F or simply F. On the other
hand, if the input focus were on a text box rather than a check
box then typing F, alone, would cause the letter to be placed in
the text box. In this instance, then, you may use only the key
combination <Alt>F.
The Tilde (~) Character
The tilde character is used by DiaLogic in two ways:
(1) To signify that the following character is to
become an Alt-key. For example:
DB().Text = "Match ~Upper/Lower Case"
The above assignment specifies a text label which has a
tilde before the ``U'' character in ``Upper'', thereby
creating an Alt-key. Thus, when <Alt> is pressed, the
letter ``U'' will be highlighted. The tilde is a special
symbol to DiaLogic and, therefore, is not printed even
though it appears in the string. Notice that, for text
labels, the tilde may be embedded anywhere in the string.
15
DiaLogic
(2) To signify that the following text is to be
printed in a different color. For example:
LB(1).Text = "Item One"
LB(2).Text = "Item Two"
LB(3).Text = "~Item Three"
.
.
.
These assignments begin to fill the LB() TYPE array
with text. LB() is a special array you'll learn more
about, but for now you should know that a list box can
print each array item in one of two colors. These two
colors are referred as the primary color and the
secondary color. Observe in our example that the
string held by the third LB() element has a leading
tilde. ``Item Three'', therefore, is displayed in the
secondary color simply because it has a tilde as its
first character. The other two items will be printed
in the primary color of the list box. Notice that in
this instance, unlike our text label example, the tilde
must be at the very beginning of the string.
To summarize, the creation of an Alt-key is a simple matter of
inserting a tilde immediately before the character you wish to be
highlighted in a text string. In this text:
DB().Text = "File ~Name:"
the N will be displayed as an Alt-key when the dialog box is
activated. Thus, pressing <Alt>N will transfer the input focus
to the dialog box element associated with, or linked to, the
label File Name.
16
Dialog Box Basics
The tilde serves a different purpose for the elements in the list
box array. In a list box two colors (also called attributes) may
be defined. The primary color is the color of all list box
elements which do not have a leading tilde; the secondary color
is used for all elements which have a leading tilde.
The DB() Array
A single array holds all the information needed to define a
dialog box. We've called this array DB, short for Dialog Box.
DB() is a two-dimension TYPE array. The size of the TYPE is 256
bytes. The first dimension, the Level, refers to a single dialog
box and it allows the DB() array to store multiple dialog boxes.
Although all dialog boxes may be generated using a Level of 1, it
is necessary to use greater Levels if dialog boxes are to be
stacked on the screen. The use of different Levels is discussed
in greater detail in Part VI: Advanced Topics.
The second dimension of the DB() TYPE array refers to the dialog
box element Sequence. As mentioned earlier on page 14, the
Sequence refers to the order in which the <Tab> key will pass
across the DBEs in a dialog box. For example, in QuickBASIC's
error messages there is generally a main list box containing the
error text, and two command buttons, <OK> and <Help>. When the
<Tab> key is pressed, the input focus travels from the list box
to the <OK> button, and then to the <Help> button. In this
example, then, the list box has a Sequence which is equal to 2
(not an error), the <OK> button is 3, and the <Help> button is 4.
An important rule to remember is that the dialog box window
always has a Sequence which is equal to 1. Further, no two DBEs
in a dialog box may have equal Sequence numbers.
17
DiaLogic
Thus, dimensioning the DB() array is based on how many dialog
boxes you will have stacked on the screen (the maximum Level),
and how many DBEs each dialog box may contain (the maximum
Sequence). The statements
'$DYNAMIC
Level% = 2 'set the Level (shown for clarity)
Sequence% = 15 'set the Sequence (shown for clarity)
REDIM DB(Level%, Sequence%) AS DialogType
show that memory is being reserved for a maximum Level of 2
stacked dialog boxes; each dialog box may have a maximum of 15
dialog box elements. The TYPE structure for DialogType is shown
next:
18
Dialog Box Basics
TYPE DialogType
BorderType AS INTEGER
Code AS INTEGER
Default AS INTEGER
Height AS INTEGER
ItemLength AS INTEGER
KeyColor AS INTEGER
Link AS INTEGER
NumberOne AS INTEGER
NumberTwo AS INTEGER
PrimaryColor AS INTEGER
SecondaryColor AS INTEGER
SelectedColor AS INTEGER
StarColor AS INTEGER
Text AS STRING * 82 'used to make TYPE 256 bytes
TextColor AS INTEGER
TextString AS STRING * 134 'used to make TYPE 256 bytes
total
TextX AS INTEGER
TextY AS INTEGER
Wdth AS INTEGER
WindowColor AS INTEGER
X AS INTEGER
Y AS INTEGER
END TYPE
The LB() Array
LB() is a one-dimension TYPE array defined as a single fixed-
length string. The length of the entire TYPE is 256 which, here,
is also the length of each LB() array element.
19
DiaLogic
The LB() array holds the items which will be used by all list
boxes in a dialog box. This is possible because each list box
accesses a specific range of LB() array elements. The use of a
single array not only simplifies the DiaLogic calling syntax, but
also allows the LB() array to be partitioned into functional
units. For example, if you are constructing a dialog box to set
up a printer you may wish to reserve LB() elements 1 to 5 for
available output ports; elements 6 to 15 for available printer
names; and elements 16 to 30 for available printer fonts. You
may then create three separate list boxes on this dialog box: the
first would access LB() elements 1 through 5 and would therefore
display the output ports; the second would access LB() elements 6
through 15, and would present available printer names; and the
third would access LB() elements 16 through 30, which would show
all available printer fonts. Any number of list boxes may be
displayed, and they are particularly suited for presenting much
information.
The ListType TYPE declaration looks like this:
TYPE ListType
Text AS STRING * 256
END TYPE
The LB() array then is dimensioned like this:
'$DYNAMIC
REDIM LB(30) AS ListType
20
Dialog Box Basics
The Dialog Box Template
The activation of a dialog box relies on instructions supplied by
a template. These instructions, which consist primarily of DB()
array assignments, provide information such as the position,
size, and color of each dialog box element. Since these
assignments may become quite lengthy, templates are often kept in
an include file so that they may be imported easily into many
different programs and so that they do not clutter program
listings. DiaLogic's template include files are distinguished by
their .DB extension. We have provided you with several templates
which are used by the demo and example programs on your
distribution diskette. Figure 3 depicts an excerpt:
DB(Level%, 1).Code = 1
DB(Level%, 1).Y = 0
DB(Level%, 1).X = 0
DB(Level%, 1).Height = 12
DB(Level%, 1).Wdth = 60
DB(Level%, 1).BorderType = -1
DB(Level%, 1).PrimaryColor = -112
DB(Level%, 1).WindowColor = -112
DB(Level%, 1).Text = "Find"
DB(Level%, 1).TextColor = 112
DB(Level%, 1).SecondaryColor = 112
DB(Level%, 1).NumberOne = 25
DB(Level%, 2).Code = 2
DB(Level%, 2).Y = 2
DB(Level%, 2).X = 14
.
.
.
Constructing a template is unfortunately the most tedious process
in creating a dialog box. However, the QuickBASIC environment
greatly simplifies the process by providing the means to transfer
text from one file to another. This process is called a
copy & paste operation.
21
DiaLogic
To assist you, we have created a generic template which consists
of just the left side of the array assignments for each dialog
box element. A sample line from the generic template would be
something like this:
DB(Level%, 1).Code =
The generic template is loaded as a document into QuickBASIC's
environment so that you may select those equates which you need
in order to construct your custom template. For example, if you
decide you want a command button in a dialog box you could copy
all equates for a command button and then paste them to your own
template. This process of copying & pasting is described
completely in Part III: Creating a Template.
Note:
The copy & paste procedure is suggested so that you
don't have to manually enter all the equate statements
each time you wish to construct a dialog box. Once you
become comfortable with the procedure, you shall
discover that transferring data between files in the
environment is useful, convenient, and expeditious.
Include Files
Include files are loaded at compile time by QuickBASIC when the
'$INCLUDE metacommand is encountered. For example, consider the
following statement:
'$INCLUDE: 'SAMPLE.DB'
22
Dialog Box Basics
This instruction causes QuickBASIC to load and compile the
contents of the file SAMPLE.DB. Notice two things about the
statement: there is a leading REM and the file name is enclosed
in single quotes. A REM symbol (`) followed by a dollar sign on
the left margin usually tells QuickBASIC to expect a metacommand.
Metacommands are special commands which are interpreted at
compile time: they are not considered part of the BASIC language
but, rather, are compiler-specific.
There are three other considerations when specifying an include
file. First, the file in quotes must exist and must be
available. To make a file available it may be necessary to use a
full directory path along with your file name. Consider the
following:
'$INCLUDE: 'C:\QB4\INCLUDE\TEMPLATENAME.DB'
This statement is similar to our previous example. However, this
time we have told QuickBASIC to use the .DB file on the C: drive
and in the \QB4\INCLUDE\ path. An alternative to explicitly
specifying the file-name path, like above, is to use the Options
Set Path... pull-down menu option. This feature allows you to
specify a path which QuickBASIC should use in the event that the
specified include file is not in the current directory. If you
plan to set an include path in QuickBASIC then you should omit a
path specification when using the include metacommand.
Second, the include file must have ``compilable'' code in it.
Once QuickBASIC reads an include file it will conduct the same
syntax checking that it performs on the rest of a program.
Therefore, insure that include files consist of valid QuickBASIC
program code.
Third, when you are in the environment you may need to inspect an
include file by using the View Included Lines pull-down menu
option. This option makes visible the contents of each include
file. If you wish to edit an include file you should first place
the cursor on the line containing the '$INCLUDE statement, then
use the View Included File pull-down menu option.
23
DiaLogic
DB() Variable Values
The following features are used when assigning elements to the
DB() array when constructing your template. Keep in mind that
DiaLogic does not verify the values passed to it. Therefore, pay
particular attention to the type and range of values each
variable may accept. For example, in our upcoming discussion
concerning the use of color, we mention that only values 0
through 7 should be used for the background attribute. Values
beyond this range should not be used and may cause undesirable
results.
Color
Colors are generally described using two terms: foreground and
background. A suitable analogy is to think of the foreground as
the color of the ``ink'' and the background as the color of the
``paper''. Although QuickBASIC's COLOR command allows foreground
and background colors to be specified separately, the color of a
character on the screen in text mode is represented internally as
a single byte. This 8-bit byte is comprised of 3 bits for the
foreground color, 3 bits for the background color, 1 bit for the
brightness of the foreground color, and 1 bit for blinking.
24
Dialog Box Basics
The figure shown next presents most of the information you need
to know in order to use color. Please try to familiarize
yourself with the 8 colors (0 through 7) available by different
combinations of the 3 color bits:
Value Color
0 Black
1 Blue
2 Green
3 Cyan
4 Red
5 Magenta
6 Brown
7 White
NOTES:
Foreground Colors:
Add 8 to above value for a bright color.
Add 16 to a color for blinking.
Background Colors:
Use only values 0 through 7.
When you decide to use a color, always choose a background value
between 0 and 7.
The allowable range for the foreground color is between 0 and 31.
However, the process of selecting a foreground color is a bit
more complex. First, select a color value between 0 and 7.
Second, if you want a bright color then add 8 to foreground value
you chose. Once the brightness is determined you will have a
foreground color between 0 and 15. Third, if you want this
foreground color to blink, add 16 to its value.
25
DiaLogic
Once you have selected both foreground and background colors you
may combine them into one byte as follows (FG is the foreground;
BG is the background):
Colr% = (FG AND 16) * 8 + ((BG AND 7)* 16) + (FG AND 15)
The previous formula will insure that illegal background values
are trapped and it provides for a flashing foreground. An easier
formula follows, but please realize that it will not allow for a
flashing foreground (which is rarely used in a dialog box) and
you must pass to it a valid background color:
Colr% = FG + 16 * BG
If you have a monochrome type of display it is best to choose
highly-contrasted combinations for the foreground and background:
bright white on black is best. Please see Appendix D: Dialog
Software Color Chart for a handy reference table.
Borders
All border types are specified by using a single number. In all
dialog box elements which allow a border style, simply use the
number below which is enclosed by the border style of your
choice:
No border
0
Single outline
1
Double outline
2
Single across, double down
3
Double across, single down
4
26
Dialog Box Basics
X, Y Coordinates
All dialog box elements require an X and Y coordinate. The Y
coordinate is the screen row, while the X coordinate is the
screen column. The dialog box window uses these coordinates to
position the dialog box as an offset to the physical upper-left
corner of the screen. All other dialog box elements use the
coordinate as offsets to the upper-left corner of the window.
Default Values
All dialog box elements which can receive the input
focus (summarized earlier in Figure 2, page 14) can be designated
with an initial default value. For example, a text box may be
pre-filled with text and a check box may be either checked or
unchecked. Except for the text box, where the default value is a
text string, the default is a number. Specific default values
will be discussed for each dialog box element in the next
section.
Understanding the Elements
The section of the manual is where each dialog box element is
fully explained. It is particularly important since a dialog box
template is constructed by gathering needed DBE definitions into
a single include file.
We have arranged the following pages so that the template
structure for each dialog box element is in a large box with an
explanatory discussion immediately following. Also, we've
summarized how each DBE is initialized and how information is
returned.
You should know that null or zero assignments are perfectly
acceptable for many of the array assignments. For example, when
creating a dialog box window you may optionally specify a
centered title in DB().Text. If you do not wish to use a title
you may assign it to null, like this:
DB().Text = ""
27
DiaLogic
As mentioned earlier, every template definition exists in generic
form in a file called TEMPLATE.DOC. You may simply transfer
portions of this file to your own include file.
For your convenience we have summarized the DBE definitions which
follow in a handy reference section in Appendix A: Dialog Box
Elements.
The Window
PURPOSE
The window is responsible for saving the underlying screen and
creating a background and frame for a dialog box. A dialog box
template has one and only one window defined.
Initial Information: None
Returned Information: None
DB(Level, 1).Code = 1
Code for window.
DB(Level, 1).Y =
Y coordinate of upper-left corner.
DB(Level, 1).X =
X coordinate of upper-left corner.
DB(Level, 1).Height =
Height of window.
DB(Level, 1).Wdth =
Width of window.
DB(Level, 1).BorderType =
Border type. If negative then window will ``explode.''
DB(Level, 1).PrimaryColor =
Color of window border. If negative then the window will cast a
shadow.
DB(Level, 1).WindowColor =
Color of window. If negative then a horizontal line will be
drawn near the bottom of the dialog box.
28
Dialog Box Basics
DB(Level, 1).Text =
Optional centered title of the window.
DB(Level, 1).TextColor =
Color of window title.
DB(Level, 1).SecondaryColor =
Color of optional bottom horizonal line.
DB(Level, 1).NumberOne =
Number of screen lines. This number may be 25, 43, 50 or 60,
depending on the type of display adapter used. Default is 25.
DISCUSSION
The window is always the first DBE in a template. The upper-left
corner of the window is designated by DB().X and DB().Y. If
either coordinate is zero than the window will be centered along
the affected axis. Thus, to center the dialog box on the screen
both DB().X and DB().Y should be set to 0. If positive integers
are used instead then the window coordinate will be interpreted
as a positive offset from the upper-left corner of the screen.
The height and width of the window are specified by DB().Height
and DB().Wdth, respectively. These dimensions are measured terms
of the number of screen characters down and across.
The color of the window border is specified by DB().PrimaryColor;
the color of the window is in DB().WindowColor; the color of the
bottom horizontal line (discussed below) is contained in
DB().SecondaryColor. A centered window title may be placed in
DB().Text. The color of the window title is defined by
DB().TextColor.
Some of the assignments we've mentioned so far have additional
potential. For example, if DB().BorderType is negative then the
window will ``explode'' when drawn; if DB().PrimaryColor is
negative then the window will appear to cast a shadow; and last,
if DB().WindowColor is negative then the window will have a
bottom horizontal line. (This horizontal line usually serves as
a divider between the upper contents of the window and a lower
29
DiaLogic
line of command buttons.) Although the numbers may be negative
you should realize that this serves as a flag only: the absolute
values are always used. The window is the only DBE that makes
use of negative-value flags in its template definition.
Finally, DB().NumberOne holds the number of screen lines
currently being used, and may be set to values such as 25, 43,
50, or 60. If DB().NumberOne is 0 then the default is 25. If
the window's Y coordinate is 0 then this value is particularly
important: it is used in calculations for centering a dialog box
along its vertical axis.
30
Dialog Box Basics
Text Box
PURPOSE
The text box allows the user to type text information directly
from the keyboard.
Initial Information: DB().TextString
Returned Information: DB().TextString, DB().NumberOne
DB().Code = 2
Code for text box.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Wdth =
Width of text box.
DB().BorderType =
Border type.
DB().PrimaryColor =
Border color.
DB().WindowColor =
Color of unselected text inside the text box window.
DB().SelectedColor =
Color of selected text.
DB().TextY =
Y coordinate for text box label.
DB().TextX =
X coordinate for text box label.
DB().Text =
Text box label. May contain a tilde for Alt-key operation.
DB().TextColor =
Color of text box label.
DB().KeyColor =
Color of the Alt-key in the text box label.
31
DiaLogic
DB().TextString =
Text box default edit string.
DB().ItemLength =
Maximum number of characters which may be entered.
DB().NumberOne =
Length of the returned string (held by DB().TextString).
DISCUSSION
The location, width, border type, and border color are specified
in the same manner as for the window.
Text in a text box may be highlighted (or selected) by dragging
the mouse while a mouse button is pressed, or by using the
<Shift> key in combination with the directional keys. Selected
text is usually marked for deletion on the next key press. Since
unselected text and selected text should be distinguishable to
the user, two different attributes are usually used for each:
DB().WindowColor is the attribute for unselected text;
DB().SelectedColor is the attribute for selected text.
Text boxes may be labelled with text, such as ``File Name''.
Such text is specified by DB().Text; the location of this text
(usually placed to the left of the text box) is indicated by
DB().TextY and DB().TextX; the color of the label is in
DB().TextColor. Further, the text box label may have an embedded
Alt-key. For example, the ``File Name'' label could have a
highlighted ``F'' to indicate that an Alt-key is present. In
this instance, you would make an assignment like this:
DB().Text = "~File Name"
The color of the Alt-key is specified by DB().KeyColor.
32
Dialog Box Basics
The text box uses DB().TextString to hold the edit string. If
DB().TextString is initialized before the dialog box is
displayed, then the text box will be filled with the specified
string. Any changes to this string will be stored in
DB().TextString. For example, suppose that we wish to present
the user with the current disk drive. We could place this
information into a variable called DefaultDrive$, then in our
template definition we could make an assignment similar to:
DB().TextString = DefaultDrive$
When DiaLogic returns information you should realize that
DB().TextString is a fixed-length string and that the string it
contains will be padded with right-side spaces. If you wish to
ignore these spaces you may use BASIC's RTRIM$ function. For
example:
TrimmedString$ = RTRIM$(DB(1, 3).TextString)
This statement removes the right-side spaces in the fixed-length
string held in DB(1, 3).TextString, and copies the result into
the conventional (variable-length) string called TrimmedString$.
But RTRIM$ removes all right-side spaces, even those
intentionally entered by the user. For this reason we have used
DB().NumberOne to hold the true length of the text box string
that was entered by the user. Thus, you may ascertain the
correct edit string by using the following statement:
EditString$ = MID$(DB().TextString, 1, DB().NumberOne)
The maximum length of the text box string may be specified in
DB().ItemLength. The text box will cease to accept characters
beyond the length specified.
33
DiaLogic
List Box
PURPOSE
The list box presents the user with a list of items through which
to scroll and ultimately from which to make a selection.
Initial Information: DB().Default
Returned Information: DB().Default
DB().Code = 3
Code for list box.DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Height =
No. items vertically within the list box borders.
DB().Wdth =
No. items horizontally within the list box borders.
DB().WindowColor =
Color of ``empty'' space within list box borders.
DB().PrimaryColor =
Color of primary list box items.
DB().SecondaryColor =
Color of secondary list box items.
DB().SelectedColor =
Color of selected items.
DB().StarColor =
Color of scroll bars.
DB().ItemLength =
Length of a single list box item.
DB().KeyColor =
Number of spaces between list box columns.
DB().BorderType =
Scroll bars: 0=none; 1=bottom; 2=side; 3=both.
DB().Link =
Link code. 0=none; >0=text-box; <0=sentence.
DB().TextY =
Y coordinate for sentence links.
DB().TextX =
X coordinate for sentence links.
34
Dialog Box Basics
DB().TextColor =
Color of sentence links.
DB().NumberOne =
LB() starting element.
DB().NumberTwo =
LB() ending element.
DB().Default =
The LB() array element number to be selected by default.
DISCUSSION
The list box is extremely powerful due to its sheer flexibility.
The upper-left corner of the list box is specified by DB().X and
DB().Y. The height and width are specified by DB().Height and
DB().Wdth in terms of the number of items to be listed vertically
and horizontally. The length of each list box item is specified
by DB().ItemLength; the number of spaces between list box columns
is specified by DB().KeyColor. Thus, the width of a list box
will equal the number of items across (DB().Wdth) multiplied by
the itemlength plus space between columns
(DB().ItemLength + DB().KeyColor).
DB().WindowColor specifies the color of the list box window. In
this assignment the foreground is used as the border color and
the background color will serve both the border and window area.
The list box border is always a single line.
35
DiaLogic
An item in a list box may be printed in one of two colors,
depending on the presence of a leading tilde. The first color is
specified by DB().PrimaryColor while the second color is
specified by DB().SecondaryColor. Any list box item which has a
tilde as its first character is printed in the secondary color;
all other items are displayed in the primary color. For example,
if we were to create a list box to display available directories
and files, we may choose to display the directory names in blue-
on-white (color 113) and the file names in black-on-white (color
112):
LB(1).Text = "~DOS"
LB(2).Text = "~QB"
LB(3).Text = "~WP50"
LB(4).Text = "COMMAND.COM"
LB(5).Text = "AUTOEXEC.BAT"
LB(6).Text = "CONFIG.SYS"
.
.
.
The above LB() items show how such assignments actually are made.
The first 3 elements represent directory names while the last 3
represent file names. In order for these items to be displayed
in the colors we specified, the list box template definition must
have assignments similar to the following:
DB(1, 3).PrimaryColor = 112
DB(1, 3).SecondaryColor = 113
Only one item in a list box is selected at a time. The
currently-selected item is displayed using the color specified by
DB().SelectedColor. Please be aware that, depending on the type
of list box, there may be no selected item until the user makes a
choice. If you do not want an item to be selected (such as for a
help list box) then use -1 for DB().SelectedColor.
36
Dialog Box Basics
Scroll bars are optional for list boxes. At least one is
recommended since it will provide a means of discerning how much
information is contained by the list box. Wide list boxes
usually have a single bottom scroll bar; narrow but tall list
boxes make better use of a right-side scroll bar. It most always
is superfluous to display both scroll bars.
The presence of a scroll bar is indicated by DB().BorderType as
follows:
DB().BorderType Resulting Scroll Bar(s)
0 No scroll bars
1 A bottom scroll bar
2 A right scroll bar
3 Both bottom and right scroll bars
The color of a scroll bar is indicated by DB().StarColor.
One of the most powerful features of DiaLogic is the ability to
link a list box item. Linking takes two forms: text-box linking
and sentence linking. Text-box links allow the currently-
selected list box item to be placed automatically in a text box.
Sentence links allow a list box item to be printed in a context-
sensitive description anywhere on the dialog box. Examples of
both link types are shown in the DEMO and explained further
below.
The type of link you wish to use is indicated by DB().Link. A
certain list box may make use of only one link type at a time,
however, list boxes in a dialog box may be using different links.
37
DiaLogic
A text-box link is created when DB().Link is greater than 0. In
this instance DB().Link must equal a Sequence number for a text
box in your template.
Note:
A Sequence number is the second subscript in the DB()
array. Thus, it is unique for each dialog box element
in a dialog box. The importance of Sequence numbers is
discussed further in the tutorial section.
Sentence links are a little more complex, and are specified when
DB().Link is less than 0. A sentence link should be used when
you wish to describe list box items to the user. For example,
suppose we use the Directory/File list box mentioned earlier. We
may want a description to appear below the list box which will
tell the user if the current item is a directory or a file, and,
if is a file, we may want to indicate which files are hidden.
Let's assume the following: if the selected item is a directory,
we'll print the message:
DIRECTORYNAME is a directory.
And for files, we'll use one sentence if it is a regular file and
another type of sentence if it is a hidden file:
FILENAME is a File.
and
The file FILENAME is hidden.
38
Dialog Box Basics
In each sentence above, the italicized name is the item name
taken directly from the list box. The rest of the sentence, like
the list box item itself, is defined in the LB() array.
If sentence links are used then the appropriate portion of the
LB() array must be filled using the following syntax:
LB().Text="[PRESTRING],[~]ITEMSTRING,[POSTSTRING]"
Notice that the optional tilde appears in front of the second
string.
The above syntax describes each LB() array string as a
concatenation of three strings: a prestring, itemstring, and
poststring. Please note that this syntax is used only when
DB().Link is less than zero. The itemstring is what will appear
in the list box and also optionally in the sentence link.
Once LB() has been properly assigned, you may construct a
sentence link using various combinations of the prestring,
itemstring, and poststring components. All sentence links use a
DB().Link value less than 0.
For example, if DB().Link were -1, and the selected item in the
list box had a corresponding LB() array string like this:
LB(5).Text = ",DIALOGIC.QLB, is a Quick Library"
then whenever the list box item ``DIALOGIC.QLB'' is selected this
sentence will appear:
DIALOGIC.QLB is a Quick Library
39
DiaLogic
In this example the prestring is null; the itemstring is
``DIALOGIC.QLB'', and the poststring is `` is a Quick Library''.
All list box link codes are summarized below. You should review
the DEMO to observe how sentence links and text-box links are
used by list boxes.
DB().Link Description
>0 Any link code greater than zero will be a text-box
link and will attempt to link to the DBE in the
template with the Sequence number specified. For
example, if DB().Link is 5, then the fifth element
in the template must be a text box.
0 No link will take place
-1 The prestring, itemstring, and poststring are
displayed together
-2 Only the prestring is displayed
-3 Only the itemstring is displayed
-4 Only the poststring is displayed
The sentence which results is displayed by the attribute defined
by DB().TextColor; the location of the sentence is specified by
DB().TextX and DB().TextY.
Since all list boxes access the LB() array we have used
DB().NumberOne and DB().NumberTwo to specify the starting and
ending elements, respectively. For example, the LB() array may
contain 100 elements. However, there may be 2 list boxes on the
current dialog box. In this instance, one list box may access
LB() array elements 1 through 60, while the other may access
elements 61 through 100. This method allows certain list boxes
to access a very specific part of the entire LB() array.
40
Dialog Box Basics
If a list box is empty you will want to assign DB().NumberOne and
DB().NumberTwo to zero. This will cause the input focus to skip
the empty list box.
Finally, DB().Default allows a list box item to be selected by
default. The number in DB().Default is the element number of the
LB() array and must fall within the range specified by
DB().NumberOne and DB().NumberTwo. If the user makes a selection
from the list box then DB().Default will be updated and may be
inspected by the calling program. If no list box item was
selected then DB().Default will be 0.
41
DiaLogic
Check Box
PURPOSE
The check box provides a simple way to turn an option ``on'' or
``off''.
Initial Information: DB().Default
Returned Information: DB().Default
DB().Code = 4
Code for check box.
DB().Y =
Y coordinate of check box's left bracket.
DB().X =
X coordinate of check box's left bracket.
DB().PrimaryColor =
Color when unselected.
DB().SelectedColor =
Color when selected.
DB().TextY =
Y coordinate for check box label.
DB().TextX =
X coordinate for check box label.
DB().Text =
Check box label. May contain a tilde for Alt-key function.
DB().TextColor =
Color of check box label.
DB().KeyColor =
Color of the alt-key in the check box label.
DB().StarColor =
Toggle star color.
DB().Default =
Default status of check box. 0=off; -1=on.
42
Dialog Box Basics
DISCUSSION
Check boxes are placed anywhere on the screen using DB().X and
DB().Y. When a check box is selected (using the arrow keys, an
Alt-key, or the mouse) a capital X will appear inside it; when
unselected, a space will appear:
[X] Selected check box
[ ] Unselected check box
The color of the space is indicated by DB().SecondaryColor and
the color of the X is indicated by DB().SelectedColor.
Check boxes may have a label associated with them in the same
sense that text boxes have a label. The location of the label is
specified by DB().TextX and DB().TextY; label text is specified
by DB().Text; label color is specified by DB().TextColor. If an
Alt-key is desired the tilde character must be used in the label
text. The color of the Alt-key is indicated by DB().KeyColor.
If the mouse is being used then a selection toggle star will
appear as the mouse is dragged across a check box. This star
marks the active check box. The color of the star is specified
by DB().StarColor.
Finally, the default value and returned information are held in
DB().Default. If the default value is 0 then the check box is
unselected; if -1 then the check box is selected.
43
DiaLogic
Option Buttons
PURPOSE
Option buttons are useful when a single option must be selected
among several choices.
Initial Information: DB().Default
Returned Information: DB().Default
DB().Code = 5
Code for option buttons.
DB().NumberOne =
Number of option buttons in this cluster.
DB().Default =
Default option button.
DB().TextString =
Location string holding coordinates for each button in the
cluster.
DB().WindowColor =
Color of button's parentheses.
DB().SelectedColor =
Color (of centered dot) when selected.
DB().StarColor =
Color of toggle star.
44
Dialog Box Basics
DISCUSSION
Option buttons are defined in clusters. The maximum number of
buttons in a cluster is 10. The exact number in the cluster
being defined is specified by DB().NumberOne. For example, the
cluster below represents a single cluster comprised of 3 option
buttons:
( )
( )
(.)
Because each button in a cluster may be placed anywhere in the
dialog box, we have not made use of a solitary X-Y coordinate
pair. Instead, we have allowed all the coordinates to be
specified in a string contained in DB().TextString. Each
coordinate is delimited from the next by a comma and, like other
DBEs, each coordinate is an offset from the upper-left corner of
the dialog box window. For example, if we wanted three option
buttons at column 10 and rows 5, 6 and 7, then the location
string would be:
DBE().TextString = "5,10,6,10,7,10"
This string is parsed by DiaLogic: it is neither necessary nor
desirable to have any embedded spaces.
The color of the option button border (that is, its parentheses)
is specified by DB().WindowColor. The color of the button when
selected (that is, the color of the centered dot) is specified by
DB().SelectedColor. As with the check box, option buttons also
have a toggle star. The color of the star is designated by
DB().StarColor.
45
DiaLogic
The button which is to be selected at the start and the one which
was selected by the user is held in DB().Default. The number it
contains corresponds sequentially to the buttons specified in
DB().TextString. Thus, in our example, button one is at 5, 10;
button two is at 6, 10; and button three is at 7, 10. If we
wanted the second button to be selected at the start then we
would assign DB().Default to 2.
You may notice that there are no assignments for labelling option
buttons. This is because all option buttons are labelled with
smart labels.
46
Dialog Box Basics
Smart Labels
PURPOSE
Smart labels may be used to place text anywhere on the screen.
But the power offered by smart labels is the ability to form an
Alt-key link to any dialog box element which can receive the
input focus. This ability makes them particularly ideal for
labelling option buttons.
Initial Information: None
Returned Information: None
DB().Code = 6
Code for smart label.
DB().Y =
Y coordinate of smart label text.
DB().X =
X coordinate of smart label text.
DB().Text =
Smart label text. May contain a tilde for alt-key function.
DB().TextColor =
Color of smart label.
DB().KeyColor =
Color of the alt-key in the smart label text.
DB().Link =
Sequence of the dialog box element which is to be an Alt-key
link to this smart label.
DB().NumberOne =
Button number for a linked option button cluster.
47
DiaLogic
DISCUSSION
Smart labels are placed on the screen at a location specified by
DB().X and DB().Y. The label text is defined by DB().Text; the
label color is specified by DB().TextColor. This information is
all that is needed if you wish simply to create a label.
However, if you wish to create an Alt-key link then you must not
only define the Alt-key but also the dialog box element to which
the Alt-key will be linked. The Alt-key character is specified
when a tilde precedes it in DB().Text. The Alt-key link is held
in DB().Link and corresponds to the dialog box element Sequence
number.
For example, if you wish to label a list box with text such as
``Available Files,'' you may wish to create an Alt-key so the
keyboard user can jump directly to this list box without the
repeated use of the <Tab> key or use of the mouse. If you decide
to make the first ``A'' the Alt-key, then your label assignment
would look something like this:
DB().Text = "~Available Files"
If the list box you wish to link to is the third in the Sequence
of dialog box elements in the template, you would assign
DB().Link as follows:
DB().Link = 3
In our example, if the user presses <Alt>A then the input focus
will be transferred to the list box.
48
Dialog Box Basics
If the smart label is used for option buttons then an additional
assignment must be made. DB().Link will still be used to
indicate the Sequence number of the option button cluster. In
addition, DB().NumberOne indicates to which button in the cluster
the smart label is to be linked. If DB().NumberOne is 2 then the
second option button in the cluster indicated by DB().Link will
be accessed when the Alt-key is pressed.
All smart labels are mouse-sensitive. If the mouse is clicked on
a smart label and a link is defined then the input focus will be
transferred as expected.
49
DiaLogic
Command Buttons
PURPOSE
Command buttons cause control to be passed back to the calling
program so that some action may be carried out. This action
usually removes the dialog box but sometimes may open an
overlaying one. Typical command buttons are <OK> and <Cancel>.
All command buttons return a unique keystroke value to the
calling program.
Initial Information: DB().Default
Returned Information: DB().Default, Ky$
DB().Code = 7
Code for command button.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Text =
Command button text. May contain a tilde for Alt-key function.
DB().PrimaryColor =
Color of angle brackets when command button is inactive.
DB().SecondaryOne =
Color of angle brackets when command button is active.
DB().WindowColor =
Color of text between angle brackets when unselected.
DB().SelectedColor =
Color of command button when selected.
DB().KeyColor =
Color of the Alt-key character.
DB().Default =
Default status: -1=on; 0=off.
DB().TextString =
Sets Ky$ return value for this command button. This should be
a valid key string, such as CHR$(27) for <Esc>.
50
Dialog Box Basics
DISCUSSION
A command button always returns control to the calling program
and, in this respect, it is said to close a dialog box. Every
dialog box will have a single active command button which is
distinguished by a pair of highlighted angle brackets. A command
button is ``pushed'' in several ways, but you must first
understand that a single default command button is defined for
every dialog box. This default is active whenever the input
focus is on a dialog box element other than a command button. An
active command button has its angle brackets highlighted.
For example, let's assume that <OK> has been defined as the
default for a dialog box which has two other command buttons:
<Cancel> and <Help>. Also, assume that there is a text box in
this dialog box. When the input focus is on the text box, <OK>
will be active because it is the default command button. But if
the input focus is transferred to <Help>, for example, then
<Help> will be active and <OK> will no longer have highlighted
angle brackets.
Command buttons may be pushed in a variety of ways:
* By using a command button Alt-key
* By pressing <Enter> when the desired command button is
active
* By pressing a command-button key
* By clicking on a command button using the mouse
All active command buttons return information in Ky$ so that the
calling program may react accordingly. The information in Ky$ is
the command-button key.
Command buttons are placed in a dialog box using DB().X and
DB().Y. The text in the command button is specified by
DB().Text, which may contain an Alt-key. The color of the Alt-
key is specified by DB().KeyColor.
51
DiaLogic
The color of an active command button is held in DB().NumberOne.
The color of the command button when it is selected with the
mouse is held in DB().SelectedColor. By convention the selected
color is inverse to the unselected color. For instance, if the
command button text is black-on-white, then it should be white-
on-black when selected. The selected color for command buttons
serves the same purpose as the toggle star of the check box and
option buttons.
The default command button must set DB().Default to -1. If none
of the command buttons in a template has the default flag, then
DiaLogic will automatically assign it to the last command button
processed. There must always be one default command button in a
dialog box.
The key to be associated with a particular command button is
defined in DB().TextString. This way, you may easily emulate
what IBM has done in the DOS 4.0 shell: most command buttons
have associated function keys, and usually appear something like
this:
<F1=Help>
In this instance you must know that <F1> has a keyboard scan code
of CHR$(0)+CHR$(59). (If scan codes are new to you they are
summarized in the QuickBASIC 4.0 Language Reference Manual,
pp. 462-463). DiaLogic will return <F1> as the last keypress if
the above command button had been pushed, and the calling program
can react the same way as if the <F1> key was actually pressed by
the user.
Additionally, you may examine DB().Default command button to
determine which one was active when the dialog box was closed.
If the value of DB().Default is -1 then that command button was
active.
52
Dialog Box Basics
Group Box
PURPOSE
The group box places an optionally-labelled box in the dialog
box. It is commonly used to visually enclose related input
regions of the dialog box.
Initial Information: None
Returned Information: None
DB().Code = 8
Code for group box.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Height =
Height of box.
DB().Wdth =
Width of box.
DB().BorderType =
Border type.
DB().SecondaryColor =
Color of group box border.
DB().Text =
Text for the top center of group box.
DB().TextColor =
Color of the text label.
53
DiaLogic
DESCRIPTION
The upper-left corner of the group box is specified by DB().X and
DB().Y. The dimensions of the box (in characters) are specified
in DB().Height and DB().Wdth. The type of border used is
indicated by DB().BorderType. The color of the group box border
is indicated by DB().SecondaryColor.
The label, if specified, will be centered at the top of the group
box. The label text is specified by DB().Text, and the color of
the label is held in DB().TextColor.
54
DiaLogic
PART III
CREATING A TEMPLATE
Creating a Template
Templates specify the exact appearance of a dialog box. Appendix
A: The Dialog Box Elements In Detail will prove to be a handy
source of reference when creating templates. It contains
extensive information about each dialog box element and should be
reviewed frequently.
Summary
(1) Making a sketch
(2) Determining the Sequence
(3) Copying & pasting
(4) Making the assignments
Creating a template consists of the four steps shown above.
First, you should decide how your dialog box is to appear to the
user. Second, you should determine a Sequence for its elements.
Third, you should copy & paste the relevant portions from the
generic template to your own template file. And fourth, you
should complete the array assignments in the new template with
values which will yield the desired dialog box.
A Detailed Example
We will present in this section an excruciatingly-detailed
account of creating a dialog box template using the steps above.
Please bear with us! The first time through may seem tedious,
but the process will grow comfortable over time.
We will construct a dialog box which could be used to query the
user for a search string.
57
DiaLogic
Note:
We have provided a full sample program called
EXAMPLE.BAS which accesses a similar dialog box which
we will constructing. You may open this program and
study it as you read the tutorial below. This program
accesses a template which is on the distribution
diskette as SEARCH.DB, and its help companion,
SEARCHH.DB. It is recommended that you manually go
through the steps below at least once.
Making a Sketch
(A Search dialog box, similar to the one in the QB editor, is
presented here...)
It may be useful to sketch the dialog box you wish to create
before you begin. Something remotely close to the figure above
will be suitable since the purpose of the sketch is merely to
serve as a prototype.
58
Creating a Template
Determining the Sequence
You should look at your sketch to determine the best Sequence for
the dialog box elements. Recall that the Sequence refers to the
path of the input focus when the user presses <Tab> or
<Shift><Tab>. Technically, Sequence is the order of the dialog
box elements in the DB() array, and this order should be arranged
so that <Tab> transfers the input focus in a predictable manner.
``Predictability'' is usually attained when pressing <Tab>
transfers the input focus in a general ``forward'' manner and
pressing <Shift><Tab> shifts it ``backward'' across the dialog
box elements.
We shall use the following Sequence in our example:
(1) The dialog box window
(2) Find What: text box
(3) Match Upper/Lowercase check box
(4) Whole Word check box
(5) <OK> command button
(6) <Cancel> command button
(7) <Help> command button
Our Sequence implies that if <Tab> is pressed while the input
focus rests on the Whole Word check box, then the input focus
will be transferred to the <OK> command button. If <Shift><Tab>
is pressed then the Match Upper/Lowercase check box will be
accessed. Please note one of the special situations in which the
input focus cannot fall on the window dialog box element: when
the input focus rests on <Help> then pressing <Tab> will skip to
the Find What text box.
Notice that we've listed the dialog box window as Sequence (1).
Although the window appears in the dialog box template, you
should realize that the input focus cannot fall on it. One rule
you should keep in mind is that the dialog box element with
Sequence number one for every template is always the window.
59
DiaLogic
Copying & Pasting
We recommend keeping dialog box templates in an include file.
This not only keeps them from cluttering your source files, but
also allows you to use them in other programs.
The easiest way to create an include file is to access the File
Create pull-down menu choice (if you are using QuickBASIC version
4.5 or later you must turn on the Full Menus feature from the
Options menu). QuickBASIC will then ask for the name and type of
file you wish to create (it uses a dialog box for this!). Enter
SEARCH.DB as the name. Be sure that the Include option is
marked. When you are finished, press <Enter>. You may now edit
your new file.
QuickBASIC allows you to view two different files simultaneously.
In order to do this you must first split the current window.
This is accomplished by executing the View Split option from the
main menu. (To undo the split later simply execute the same
command.) Once there are two edit windows on the screen you may
switch the cursor between them and QuickBASIC's Immediate Window
by pressing <F6> or <Shift><F6>.
Our purpose for splitting the window is to display the
TEMPLATE.DOC file in one part of the display and SEARCH.DB in the
other. Having both on-screen will allow you to copy & paste from
the generic TEMPLATE.DOC template to your own SEARCH.DB template.
Place the cursor in the upper-half of the screen. Then, load
TEMPLATE.DOC as a document using the File Load option from the
main menu. Scroll down until you see the following line:
DB(Level%, 1).Code = 1 'Window Code
This is the first array assignment for the window dialog box
element which has a DBE code of 1 (see page 14).
60
Creating a Template
You should select the text from DB(Level%, 1).Code = to
DB(Level%, 1).NumberOne = by using the arrow keys while the
<Shift> key is held down. Once the entire text is properly
selected, let go of the keys. Then press <Ctrl><Insert>. This
last key sequence copies the selected (highlighted) text onto the
QuickBASIC clipboard.
You may now press <F6> until the cursor rests in the SEARCH.DB
window. Position the cursor and press <Shift><Insert> to paste
the contents of the clipboard. The text you selected from the
generic template should appear (sometimes there is a delay when
copying or pasting).
Our process of selecting text with <Shift><arrow>, copying text
with <Ctrl><Insert>, and inserting text with <Shift><Insert> is
the copy & paste operation to which we referred earlier. Such a
method is highly-suggested whenever you need to create a dialog
box template.
The remaining copy & paste operations are straightforward: simply
continue the process until all seven dialog box element
definitions are properly copied. Since the window template
definition already has been transferred, only these remaining
elements must be copied:
* one text box
* two check boxes
* three command buttons
The text box generic template array assignments may be copied in
a manner exactly like the window. Simply scroll through
TEMPLATE.DOC until you see DB().Code = 2, which signifies the
beginning of the text box array assignments. Copy & paste all
the text box assignments into the SEARCH.DB template using the
same process as for the window.
61
DiaLogic
At this point two check boxes and three command buttons must be
appended to the SEARCH.DB template. These transfers may be
accomplished by only two copy operations. Copy the array
assignments grouped with the check box, beginning with the
assignment DB().Code = 4. Transfer the cursor to the SEARCH.DB
template and press <Shift><Insert> twice. Notice that two check
box array assignments have been pasted. Thus, once the array
assignments for a dialog box element have been copied onto the
clipboard they may be pasted as many times as needed. It is a
good practice to leave a blank line between each DBE in a
template. This will enhance readability.
You may finish the copy & paste exercise by transferring three
command button definitions, which begin with DB().Code = 7 in the
generic template.
You now have all the information from the generic template for
the Search dialog box. You should save your work so far using
the File Save pull-down menu option while the cursor is in the
SEARCH.DB edit window. At this time you may wish to ``un-split''
the SEARCH.DB edit window since most upcoming work will be
concerned with this file.
Your job now involves giving a value to each DB() element. In
order to do this you may need to refer to Appendix A: Dialog Box
Elements. Also, it may be desirable to turn QuickBASIC's Syntax
Checking feature off (by using the pull-down menu system), and to
insure that the Overwrite insert mode is on (by pressing the
<Ins> key until the cursor becomes full-size).
62
Creating a Template
Making the Assignments
Let's begin with the window definition. The empty definition
from the generic template will appear something like this:
DB(Level%, 1).Code = 1
DB(Level%, 1).Y =
DB(Level%, 1).X =
DB(Level%, 1).Height =
DB(Level%, 1).Wdth =
DB(Level%, 1).BorderType =
DB(Level%, 1).PrimaryColor =
DB(Level%, 1).WindowColor =
DB(Level%, 1).Text =
DB(Level%, 1).TextColor =
DB(Level%, 1).SecondaryColor =
DB(Level%, 1).NumberOne =
Notice that DB().Code is already defined and that all subscripts
have the second dimension already set to 1. We were able to
complete the Sequence subscripts only for the window since it is
always the first dialog box element in a template. The first
dimension, the box Level number, will remain as the variable
Level% for now.
You may use the QuickBASIC editor to assign values to the DB()
array elements. We shall make both Y and X equal to 0 because we
want the box automatically centered on the screen when it is
displayed. Height will be 11 and width will be 60.
For the window DB().BorderType allows us to define the border
style and an explode option. Since we do not wish the window to
explode we'll set border type to 1, which represents a single
outline (see Borders on page 26).
63
DiaLogic
DB().PrimaryColor controls the border color for the window and
also allows a shadow to be drawn if the value of the color is
negative. Since we do want a shadow we'll set DB().PrimaryColor
to -112. DiaLogic will use the absolute value of
DB().PrimaryColor to determine the color (see Appendix D: Dialog
Software Color Chart).
DB().WindowColor is the color of the inside window space. We
wish this to be consistent with the border so we'll use 112.
However, we also want a bottom horizontal line to cover the
command buttons. For this reason we'll use the negative value -
112 since a negative window color produces a bottom divider line.
DB().Text will produce a centered window title. For this dialog
box we'll use ``Search'' as the title. DB().TextColor is the
color of the title. We'll use 112. DB().SecondaryColor is the
color of the horizontal line. We'll use 112 for that too.
Finally, DB().NumberOne holds the number of screen lines which
will be present when the dialog box is displayed. We will use 25
for this value since the screen will be in 25-line mode.
When you are finished your template should look like the
following:
DB(Level%, 1).Code = 1
DB(Level%, 1).Y = 0
DB(Level%, 1).X = 0
DB(Level%, 1).Height = 11
DB(Level%, 1).Wdth = 60
DB(Level%, 1).BorderType = 1
DB(Level%, 1).PrimaryColor = -112
DB(Level%, 1).WindowColor = -112
DB(Level%, 1).Text = "Search"
DB(Level%, 1).TextColor = 112
DB(Level%, 1).SecondaryColor = 112
DB(Level%, 1).NumberOne = 25
64
Creating a Template
DiaLogic will use all the information above when displaying the
dialog box window and anything about the window (such as its
color, location, size, etc.) can be altered simply by changing
the a value in the DB() array.
We will continue in this manner until all the elements are
assigned values. Keep in mind that although this is no doubt a
tedious process, once a dialog box template is created it may be
used in any program with no modification.
The next element is the text box. It should use the following
values, and you will have to add the Sequence number "2" to the
second DB() array subscript (this corresponds to the DBE Sequence
we had established earlier, on page 59):
DB(Level%, 2).Code = 2
DB(Level%, 2).Y = 2
DB(Level%, 2).X = 14
DB(Level%, 2).Wdth = 44
DB(Level%, 2).BorderType = 1
DB(Level%, 2).PrimaryColor = 112
DB(Level%, 2).WindowColor = 112
DB(Level%, 2).SelectedColor = 7
DB(Level%, 2).TextY = 3
DB(Level%, 2).TextX = 3
DB(Level%, 2).Text = "~Find What:"
DB(Level%, 2).TextColor = 112
DB(Level%, 2).KeyColor = 127
DB(Level%, 2).TextString = ""
DB(Level%, 2).ItemLength = 50
DB(Level%, 2).Default = 0
Remember, a character which follows a tilde will become an
Alt-key when the dialog box is run. Thus, pressing <Alt>F will
access the check box defined above. Further, we've left
DB().TextString equal to null since we do not wish a default
string to be specified.
65
DiaLogic
The Match Upper/Lowercase check box is defined below:
DB(Level%, 3).Code = 4
DB(Level%, 3).Y = 6
DB(Level%, 3).X = 3
DB(Level%, 3).PrimaryColor = 112
DB(Level%, 3).SelectedColor = 112
DB(Level%, 3).TextY = 6
DB(Level%, 3).TextX = 7
DB(Level%, 3).Text = "~Match Upper/Lower Case"
DB(Level%, 3).TextColor = 112
DB(Level%, 3).KeyColor = 127
DB(Level%, 3).StarColor = 113
DB(Level%, 3).Default = -1
The next check box is defined as follows:
DB(Level%, 4).Code = 4
DB(Level%, 4).Y = 7
DB(Level%, 4).X = 3
DB(Level%, 4).SecondaryColor = 112
DB(Level%, 4).SelectedColor = 112
DB(Level%, 4).TextY = 7
DB(Level%, 4).TextX = 7
DB(Level%, 4).Text = "~Whole Word"
DB(Level%, 4).TextColor = 112
DB(Level%, 4).KeyColor = 127
DB(Level%, 4).StarColor = 113
DB(Level%, 4).Default = 0
66
Creating a Template
The <OK> command button is defined as follows:
DB(Level%, 5).Code = 7
DB(Level%, 5).Y = 10
DB(Level%, 5).X = 10
DB(Level%, 5).Text = "OK"
DB(Level%, 5).PrimaryColor = 112
DB(Level%, 5).WindowColor = 112
DB(Level%, 5).SelectedColor = 7
DB(Level%, 5).KeyColor = 127
DB(Level%, 5).SecondaryColor = 127
DB(Level%, 5).Default = -1
DB(Level%, 5).TextString = CHR$(13)
The command button above will be the default since we've set
DB().Default to -1. This implies that <OK> will be active and
thus highlighted at all times unless another command button is
accessed. It is customary to indicate an <OK> command button as
the default. Further, we have set DB().TextString to CHR$(13),
the ASCII character for <Enter>. Therefore, DiaLogic will make
Ky$ equal to CHR$(13) if the <OK> command button is pushed.
67
DiaLogic
The <Cancel> and <Help> command buttons and the last dialog box
element in the template are defined as follows:
DB(Level%, 6).Code = 7
DB(Level%, 6).Y = 10
DB(Level%, 6).X = 24
DB(Level%, 6).Text = "Cancel"
DB(Level%, 6).PrimaryColor = 112
DB(Level%, 6).WindowColor = 112
DB(Level%, 6).SelectedColor = 7
DB(Level%, 6).KeyColor = 127
DB(Level%, 6).SecondaryColor = 127
DB(Level%, 6).Default = 0
DB(Level%, 6).TextString = CHR$(27)
DB(Level%, 7).Code = 7
DB(Level%, 7).Y = 10
DB(Level%, 7).X = 43
DB(Level%, 7).Text = "~Help"
DB(Level%, 7).PrimaryColor = 112
DB(Level%, 7).WindowColor = 112
DB(Level%, 7).SelectedColor = 7
DB(Level%, 7).KeyColor = 127
DB(Level%, 7).NumberOne = 127
DB(Level%, 7).Default = 0
DB(Level%, 7).TextString = CHR$(0) + CHR$(59)
DB(Level%, 8).Code = 0 '<-- very important!
The command buttons above are similar to the <OK> command button.
Notice that DB().Default is set to 0 for both. The reason is
that we've already assigned the default button. If we had tried
to define <Help> as the default in addition to <OK>, then
DiaLogic would use the command button with the higher Sequence
and would therefore accept <Help> as the default.
68
Creating a Template
We have associated the <Esc> key (CHR$(27)) with <Cancel>, and
the <F1> key (CHR$(0) + CHR$(59)) with <Help> so that DiaLogic
will return the appropriate key in Ky$.
Observe that <Help> has an Alt-key. Neither the <Cancel> nor the
<OK> command buttons, by convention, contains an Alt-key.
Finally, the most important thing about the end of a template is
that the last Sequence number must assign DB().Code to 0 !
At this point you have completed your first dialog box template.
Congratulations! You should now use the File Save option and
remember that your template is being saved as the SEARCH.DB
include file.
Before going on, please examine the new template presented below.
This template defines the Help dialog box which will be presented
when the user requests help while using the Search dialog box.
If you wish to construct this template using the procedure
described for the Search dialog box, then please save it as
SEARCHH.DB. Alternatively, you can later use this template since
it exists on the distribution diskette as SEARCHH.DB.
DB(Level%, 1).Code = 1
DB(Level%, 1).Y = 10
DB(Level%, 1).X = 4
DB(Level%, 1).Height = 10
DB(Level%, 1).Wdth = 35
DB(Level%, 1).BorderType = 1
DB(Level%, 1).PrimaryColor = -112
DB(Level%, 1).WindowColor = -112
DB(Level%, 1).Text = "Help"
DB(Level%, 1).TextColor = 112
DB(Level%, 1).SecondaryColor = 112
DB(Level%, 1).NumberOne = 25
69
DiaLogic
LB(1).Text = "This is an example of a Help"
LB(2).Text = "dialog box. This help text"
LB(3).Text = "actually is contained in a"
LB(4).Text = "list box!"
DB(Level%, 2).Code = 3
DB(Level%, 2).Y = 2
DB(Level%, 2).X = 2
DB(Level%, 2).Height = 4
DB(Level%, 2).Wdth = 1
DB(Level%, 2).WindowColor = 112
DB(Level%, 2).PrimaryColor = 112
DB(Level%, 2).SecondaryColor = 112
DB(Level%, 2).SelectedColor = -1
DB(Level%, 2).StarColor = 112
DB(Level%, 2).ItemLength = 30
DB(Level%, 2).KeyColor = 0
DB(Level%, 2).BorderType = 0
DB(Level%, 2).Link = 0
DB(Level%, 2).TextY = 0
DB(Level%, 2).TextX = 0
DB(Level%, 2).TextColor = 112
DB(Level%, 2).NumberOne = 1
DB(Level%, 2).NumberTwo = 4
DB(Level%, 2).Default = 0
DB(Level%, 3).Code = 7
DB(Level%, 3).Y = 9
DB(Level%, 3).X = 15
DB(Level%, 3).Text = "~OK"
DB(Level%, 3).PrimaryColor = 112
DB(Level%, 3).WindowColor = 127
DB(Level%, 3).SelectedColor = 7
DB(Level%, 3).KeyColor = 127
DB(Level%, 3).SecondaryColor = 127
DB(Level%, 3).Default = -1
DB(Level%, 3).TextString = CHR$(13)
DB(Level%, 4).Code = 0
70
Creating a Template
This template demonstrates a way to use a list box to present
paragraph-oriented text. This list box is neither linked nor
does it select an element. When DB().SelectedColor is -1 for a
list box, a highlight bar will not be visible. Also, this list
box has a Sequence of 2 and will access elements 1 through 5 of
the LB() array since DB().NumberOne and DB().NumberTwo are
defined for these values.
When the help dialog box is used it would most likely be at
Level 2, which will allow it to be drawn ``on top of'' the Search
dialog box. The method for doing this is discussed in Part VI:
Advanced Topics.
71
DiaLogic
PART IV
GENERATING A DIALOG BOX
Generating a Dialog Box
In this section we explain how to use dialog boxes in your own
programs, culminating with a full program to generate the Search
dialog box created in Part III: Creating a Template.
The call to DiaLogic allows you to do several things to a dialog
box depending on the arguments used. One argument we mentioned
earlier called Action% will become very important when generating
dialog boxes: it determines what will happen after the call.
Briefly, the Action allows you to:
* display a dialog box from its template
* remove a dialog box from the screen
* stack a dialog box over an existing one
* update the elements within a dialog box
* process the dialog box alternately with the calling
program
It should be clear that Action allows you to display dialog boxes
in different ways and, as you will soon discover, distinguishes
single-tasking from multi-tasking dialog boxes.
Preparing for the Call
While all the steps need not be taken, there are a few things
which should be considered when preparing to make a call to
DiaLogic. These steps are discussed next.
* Including DIALOGIC.BI
* Initializing the Mouse
* REDIMing DiaLogic's Arrays
* Setting the Level
* Including the Dialog Box Template
* Setting the Action
* Setting the Focus
73
DiaLogic
Including DIALOGIC.BI
It is important to place following statement at the top of the
calling program:
'$INCLUDE: 'DIALOGIC.BI'
This makes available to QuickBASIC the DiaLogic DECLARE
statements for both the assembler and BASIC routines, and the
TYPE declarations for both the DB() and LB() arrays.
Initializing the Mouse
Before first using DiaLogic the calling program should check to
see if a mouse is present and, if so, it should reset the mouse
driver software to its default values. We've given you an
assembler subroutine called InitMouse in DIALOGIC.QLB for
initializing the mouse driver:
DECLARE SUBROUTINE InitMouse(There%)
CALL InitMouse(There%)
If a mouse is present then There% will be set to -1. If no mouse
is installed then There% will be 0. In order for a mouse to be
operational both the mouse hardware and software driver must be
available to the computer.
Because InitMouse resets the mouse driver values (the mouse
cursor color, its travel range and sensitivity, etc), it should
probably be called only once at the start of a program.
74
Generating a Dialog Box
After initializing the mouse you should insure that its cursor is
visible. We've given you two assembler routines which should be
used for this purpose. One is called ShowCursor, and the other
is TextCursor. Consider the following program fragment:
DECLARE SUBROUTINE ShowCursor()
DECLARE SUBROUTINE TextCursor(FG%, BG%)
CALL ShowCursor()
FG% = 0
BG% = 4
CALL TextCursor(FG%, BG%)
ShowCursor needs no arguments and, on most machines, it will
reveal the mouse cursor on the screen. TextCursor is necessary
when this does not work, and we recommend using both routines to
insure that the mouse cursor can be seen. TextCursor is more
powerful than ShowCursor since it allows you to set the mouse
cursor's foreground and background colors in FG% and BG%,
respectively. We suggest using 0 for FG% and 4 for BG%, which
produces a cursor like the one in QuickBASIC's environment.
75
DiaLogic
In many cases a calling program will need to print information on
the screen. It is necessary to turn the mouse cursor off before
printing. You may do this using HideCursor but you should
remember to issue a complimentary ShowCursor call. HideCursor is
declared and called like this:
DECLARE SUBROUTINE HideCursor()
CALL HideCursor()
HideCursor, like ShowCursor, requires no arguments.
Note:
If HideCursor is not used before printing on the screen
then the background attribute for the character printed
in the mouse cursor's location may not be correct. The
result is a mouse cursor ``imprint'' which is generally
not acceptable.
The DECLARE statements were shown immediately before their
respective calling syntaxes in the above examples for
documentation purposes: they should always be at the very top of
the calling program's main module. But these DECLARE statements
are present in the include file DIALOGIC.BI. Thus, if you
include DIALOGIC.BI at the top of your program, then the DECLARE
statements will be available and therefore do not have to be
explicitly entered.
76
Generating a Dialog Box
Hence, if a mouse is available the assembler routines InitMouse,
ShowCursor, TextCursor, and HideCursor should provide full
control over its initialization and its cursor's color and
visibility. If a mouse is not present then DiaLogic will
function very well using the keyboard alone.
It is not necessary to use any of these mouse initialization
steps if no mouse is present. If the calling program will never
make use of a mouse then you may consider removing mouse-related
code from DIALOGIC.BAS. This process is discussed in Appendix B:
Modifying DIALOGIC.BAS.
REDIMing DiaLogic's Arrays
Before you include your dialog box template and before you make
any calls to DiaLogic you must REDIM two arrays. These arrays
will hold the dialog box template and any list box items. We
suggest using dynamic arrays so that they may be redimensioned
using the REDIM statement as needed by your program (if you
intend to use huge arrays, please see the note on page 94):
'$DYNAMIC
REDIM DB(2, 30) AS DialogType
REDIM LB(50) AS ListType
The preceding example dimensions DB() in such a way that memory
is set aside for up to 2 dialog boxes having a maximum of 30
elements each. Recall that the first subscript in DB() refers to
the dialog box Level number, while the second subscript refers to
the Sequence of a particular dialog box element. When you
initialize DB() you must insure that it is dimensioned correctly
for both the maximum number of dialog boxes to be stacked on the
screen at one time (the Level) and the number of dialog box
elements (i.e., the highest Sequence number) with which it will
be used.
77
DiaLogic
The LB() array is dimensioned here at a conservative 50 elements.
This means that a single list box can contain a maximum of 50
items. The exact number used in dimensioning this array may be
tailored to your specific needs. If you use no list boxes in a
dialog box you still must at least define the array, but you may
specify 0 elements like this:
REDIM LB(0) AS ListType
This way, a compiler error will not be generated and, at the same
time, no memory will be wasted when allocating space for the
array.
Setting the Level
The Level is represented by the variable Level% and allows the
DB() array to hold more than one template at once. When more
than one Level is present dialog boxes may be stacked and
unstacked. DiaLogic is smart because it preserves all the
choices on a dialog box before it allows a new one to be stacked
on top of it. This feature enables an overlaying dialog box,
such as Dialog Box No. 2 below, to be removed from Dialog Box No.
1 beneath it. Thus, when DiaLogic is called to re-activate
Dialog Box No. 1 it is able to resume processing precisely where
it had been.
(Figure shows one box atop another.)
Figure 8: Stacked dialog boxes at two Levels
78
Generating a Dialog Box
Stacked dialog boxes produce an aesthetic screen. However, each
dialog box must be retained in the DB() array and, therefore,
stacked dialog boxes require more memory.
Recall that the array subscripts in the template created in Part
III: Creating a Template remain like this:
DB(Level%, 1).Code = 1
DB(Level%, 2).X = 0
DB(Level%, 3).Y = 0
.
.
.
Therefore, it is up to you to assign a positive integer value to
the variable Level% before including the dialog box template.
The example below shows a dialog box template which is being set
at Level 1. Notice that the Level assignment statement precedes
the template, so that QuickBASIC compiles the DB() array
assignments using 1 as the value of the first subscript:
Level% = 1
'$INCLUDE: 'TEMPLATENAME.DB'
<<DB(Level%, 1).Code = 1>>
<<DB(Level%, 2).X = 0>>
<<DB(Level%, 3).Y = 0>>
.
.
.
79
DiaLogic
The previous program fragment will work the same way as the
fragment below which states the array assignments explicitly and
does not use an include file:
DB(1, 1).Code = 1
DB(1, 2).X = 0
DB(1, 3).Y = 0
.
.
.
Note:
The reason you should not replace Level% with 1 in your
template files is that the template would then only be
usable at Level 1. If you wished to stack the dialog
box defined by the template onto an existing dialog
box, you would require a Level of 2. If ``1'' were
hard-coded in the template definition you would be
required to change all subscripts for DB() in the
template to ``2''. For this reason, hard-coding the
Level subscript for the DB() array in template files is
not recommended.
Including the Dialog Box Template
Including a template, such as the SEARCH.DB dialog box template
we created in Part III: Creating a Template, is a simple matter
of using the following command:
'$INCLUDE: 'TEMPLATENAME.DB'
80
Generating a Dialog Box
Setting the Action
Most of the dialog boxes you create will simply query the user
first and then return to the calling program. These types of
dialog box are referred to as single-tasking since only one
program (i.e., DiaLogic) runs while the dialog box is active.
More advanced dialog boxes are distinguished by their ability to
return to the calling program after or even while they are
displayed. These dialog boxes are referred to as multi-tasking
since at least two programs (i.e., DiaLogic and the calling
program) are alternately executed while the dialog box is active.
In terms of tasking abilities, the type of dialog box is
determined by the Action% argument in the call to DiaLogic.
Page 82 shows that Action has 8 values ranging from 0 to 7. When
Action is 0, for example, the dialog box is displayed and removed
using a single call. Other Action values allow for higher
complexity however they require multiple calls. Since an
understanding of Action is extremely important we have devoted
Part VI: Advanced Topics towards demonstrating its use.
Note:
It may be helpful to know that these Action values are
similar to those used in other Dialog Software
products, such as QuickPak Professional's multi-tasking
pull-down menu system.
81
DiaLogic
Action%
Value Function
0 Opens a dialog box; gathers information; removes the
dialog box from the screen.
1 Opens a dialog box; immediately returns to the
calling program with Action set to 3.
2 Refreshes the contents or status of all text boxes,
list boxes, check boxes, and option buttons by
examining the DB() array.
3 Calls DiaLogic in a multi-tasking (polled) mode.
Action remains 3 until a key is pressed or the mouse
is used, in which case Action becomes 4.
4 Signals that input was received while in polled mode.
5 Closes a dialog box by removing it from the screen.
6 Opens a dialog box; gathers information; and returns
to the calling program. The dialog box remains on
the screen until action 5 is used. Alternatively, a
new dialog box can be stacked using the next Level;
once it is closed and removed, the Action-6 dialog
box may be reactivated using Action 2 followed by
Action 7.
7 Terminates the multi-tasking action. Once used, the
dialog box will resume execution as if it had been
called with Action=6.
Our example in this section will illustrate the use of Action 0
only. Action-0 dialog boxes are ideal for most applications.
More complex dialog boxes are discussed in Part VI: Advanced
Topics.
82
Generating a Dialog Box
Setting the Focus
Before calling DiaLogic, the argument Focus% specifies the DBE on
which the input focus should rest when the dialog box is first
generated. If you set Focus to 0, then DiaLogic will place the
input focus on the DBE with the lowest Sequence number which can
receive the input focus (see Figure 2, page 14).
After the call, Focus% contains the DBE on which the input focus
last rested. This information is useful if the calling program
needs to know the exact dialog box element which was last
accessed before control was returned to the calling program.
For example, if we created a simple dialog box which had an <OK>
and a <Help> command button only, we could assume the template
consists of Sequence (1) the window, (2) the <OK> command button,
and (3) the <Help> command button. If we wished the input focus
to be on <OK> when the dialog box is displayed then we would set
Focus% to 2, since the <OK> button has a Sequence number of 2.
Another possibility would be to place the input focus on the
<Help> button. Here, we would set Focus% to 3. Please realize
that, for this dialog box, if Focus% were set to 0, then the <OK>
button would be the first available DBE and therefore would
receive the input focus.
Ky$
The variable Ky$ is the only argument which cannot be used to
pass a value to DiaLogic. Any initial value it has is simply
ignored. However, Ky$ becomes very useful when DiaLogic returns
to the calling program. Ky$ will always hold a key, such as
<Enter>. But the key it contains may have been either pressed on
the keyboard or returned by a command button. Recall that each
command button specifies a key to which it is uniquely
associated. This command-button key value is a string returned
in Ky$.
Pressing <Esc> will always return CHR$(27) in Ky$. However
pressing <Enter>, double-clicking on a list box item, or clicking
on a command button will always return the command-button key for
the active command button.
83
DiaLogic
Making the Call
The call to DiaLogic has the following syntax:
CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
At this point, the pre-call instructions discussed may be added
for a resulting program segment which is something like this:
DEF INT A-Z 'recommended if possible
'$INCLUDE: 'DIALOGIC.BI' 'include TYPE definitions
'$DYNAMIC 'make arrays dynamic
REDIM DB(2, 30) AS DialogType 'REDIM arrays
REDIM LB(50) AS ListType 'REDIM arrays
Level% = 1 'set the Level
'$INCLUDE: 'SEARCH.DB' 'include the template
Action% = 0 'set the Action
Focus% = 0 'set the Focus
'make the call
CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
The above instructions will generate the Search dialog box and
patiently wait for input. The first statement, DEF INT A-Z, is
useful if your program can operate using integer variables as a
default. In general, this statement can increase a program's
execution speed. Remember that the dialog box is closed when the
user presses <Esc>, <Enter>, clicks on a command button or
double-clicks on a list box item. Once one of these events
occurs, the dialog box will be removed from the screen and the
underlying image will be restored. At this point the calling
program regains control and may ``process'' its call to DiaLogic.
84
Generating a Dialog Box
Processing the Call
Processing the call consists of analyzing information returned by
DiaLogic. Most of the information you will need is held by the
same DB() array used when calling DiaLogic. So, knowing which
options were selected is a simple matter of accessing DB(). The
other variables which are used as arguments in the call to
DiaLogic may also be useful, and the information they contain
when Action is 0 is summarized below (further discussion for
other Actions is provided in Part VI: Advanced Topics):
Variable Returned when Action% is 0
DB() For all DBEs (except the text box) information is
returned in DB(1, SequenceNo).Default. The text
box uses both DB(1, SequenceNo).TextString (to
hold the input string) and DB(1,
SequenceNo).NumberOne (to hold the string
length).
Action% Remains 0.
Focus% Contains the DBE Sequence number on which the input
focus rested when the dialog box was closed.
Ky$ Contains the keystroke used to close the dialog box.
The first thing we should determine once control is returned to
the calling program is whether or not to process the dialog box.
If the user pressed <Esc> or used the <Cancel> command button
then the information returned by DiaLogic should be ignored and
the calling program should continue doing something else.
However, if the user pressed <Enter> and <Cancel> was not active
then the calling program should interpret and possibly react to
choices made.
The Search dialog box presented earlier has a text box, two check
boxes, and three command buttons and it is shown again below for
your convenience. You may also feel the need to refer to the
SEARCH.DB template in order to fully-appreciate the ensuing
discussion. This template appears in Part III: Creating A
Template.
85
DiaLogic
Search
Find What:
[ ] Match Upper/Lower Case
[ ] Whole Word
< OK > < Cancel > < Help >
In deciding not to process the dialog box we must examine Ky$.
If it is equal to CHR$(27), ASCII for <Esc>, then either the
<Esc> key was pressed or <Cancel> was active when the dialog box
was closed. Recall that a dialog box is closed when a command
button is ``pushed'', an Alt-key is used, or if the mouse is used
to double-click on a list box item. If the <Cancel> button was
indeed pushed then we may assume that the user wished to nullify
selections made on the dialog box.
If we discover that a cancel operation has not been chosen, then
we should process the dialog box by analyzing information entered
by the user.
86
Generating a Dialog Box
Command buttons are usually the first DBEs to be analyzed since
they often direct what the calling program is to do next. We've
already discussed what should happen if <Cancel> is chosen. In
our SEARCH.DB example, there two additional command buttons:
<OK>, and <Help>. Since DB().TextString for command buttons
specifies what should be returned in Ky$, our SEARCH.DB template
uses the following values:
Command Button DB().TextString Meaning
<OK> CHR$(13) <Enter>
<Cancel> CHR$(27) <Esc>
<Help> CHR$(0) + CHR$(59) <F1>
Thus, if <Help> is chosen or if <F1> is pressed then Ky$ will be
equivalent to CHR$(0) + CHR$(59). Thus, DiaLogic will return the
same value when either <Help> or <F1> is used.
An alternative is to detect which command button was pushed by
examining DB().Default. Only one command button will have its
DB().Default value set to -1: this is the command button which
was pushed. All other command buttons in the template will have
DB().Default equal to 0.
If <Help> was pushed then we should print a help message. After
the help message we will want to display the Search dialog box
again. (To stack a help message dialog box onto the Search
dialog box, please refer to Part VI: Advanced Topics.)
87
DiaLogic
If <OK> is pushed then we should gather information about what
string to find, and whether the search should be case-sensitive
or for whole words only. The search string is available in
DB(1, 2).TextString and its length is held in DB(1, 2).NumberOne.
The other information needed is in DB(1, 3).Default, which will
be -1 if Match Upper/Lower Case is checked, and in DB(1,
4).Default, which will be -1 if Whole Words is checked.
We have offered a decision-making process which looks like this:
.
.
.
If not <Cancel> then
If <Help> then
Print help message
Generate Search dialog box again
End if
If <OK> then
Get the search string
Get the case-matching requirement
Get the whole-words only requirement
End if
End if
.
.
.
88
Generating a Dialog Box
Of course, you may use whatever logic is best for you. We are
presenting this method as one possible approach.
Our final program, listed below, will generate a dialog box and
then processs it:
DEF INT A-Z 'make variables integer
'$INCLUDE: 'DIALOGIC.BI' 'include TYPE definitions
'$DYNAMIC 'make arrays dynamic
REDIM DB(2, 30) AS DialogType 'dimension DB()
REDIM LB(0) AS ListType 'dimension LB()
Level% = 1 'set the Level
'$INCLUDE: 'SEARCH.DB' 'include the dialog box
'template
Action% = 0 'use Action 0
Focus% = 0 'set Focus
'make the call
CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
IF Ky$ <> CHR$(27) THEN 'check for <Esc> or <Cancel>
IF Ky$ = CHR$(0) + CHR$(59) THEN 'check for <F1> or <Help>
LOCATE 1,1 'locate cursor
PRINT "You pressed <Help>." 'print a message
END IF
IF Ky$ = CHR$(13) THEN 'check for <Enter> or <OK>
'get the search string
Search$ = RTRIM$(DB(Level%, 2).TextString
'get right-side spaces
Search$ = Search$ + SPACE$(DB(Level%, 2).NumberOne -
LEN(Search$))
'get Upper/Lower Case
ULCase = DB(Level%, 3).Default
'get Whole Words
WWords = DB(Level%, 4).Default
END IF
END IF
89
DiaLogic
PART IV
CREATING STANDALONE PROGRAMS
DiaLogic
Compiling DiaLogic
Since DiaLogic is supplied to you as a BASIC module, you will
need to create a DiaLogic object file which then can be linked
with programs that make calls to it. You can compile
DIALOGIC.BAS from the command line as follows:
BC DIALOGIC /O;
This will create DIALOGIC.OBJ. You should also compile your
programs which call DiaLogic using this syntax:
BC BASICPROGRAM /O;
You will need to compile all your own modules separately.
Note:
If you plan to use huge arrays, DiaLogic is prepared:
the DB() and LB() TYPE definitions have structures
which are a power-of-two in length. Be sure to specify
the /AH command line switch when compiling.
Linking with DiaLogic
Once you have compiled all your programs to .OBJ files, you will
need to create a final stand-alone .EXE file before it can be run
from DOS. Keep in mind that because DiaLogic uses external
assembler routines you will need to specify its assembler library
file, DIALOGIC.LIB, when linking.
If you are compiling and linking manually from DOS then you would
specify all your BASIC-compiled object modules, along with
DIALOGIC.LIB, like this:
LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC.LIB
94
Creating Standalone Programs
If you prefer you can start LINK without any options and wait for
it to prompt you for the information it needs. To do this just
type:
LINK
You may also specify more than one library when linking. For
example, if you need assembler routines from both DiaLogic and a
library file called PRO.LIB, you may tell LINK to use both of
them:
LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC PRO
You may also add single object modules at LINK time, even if they
are not present in a library at all:
LINK BASICPROGRAM+DIALOGIC.OBJ+OBJECT,,NUL,DIALOGIC PRO
If you do wish to combine several libraries into a single .LIB
file, that is quite easy too. Though the LIB library manager is
usually employed to add or remove object modules, you may also
add one or more complete libraries like this:
LIB LIBRARY1.LIB+LIBRARY2.LIB+LIBRARY3.LIB
One useful LINK option you should be aware of is the /EX command
line switch. When LINK is invoked with /EX, it creates an .EXE
file in a special ``packed'' format. Not unlike the various
archive programs, the code and data are compressed to take up
less disk space. When the program is run, the first code that
actually executes is an unpacking routine that puts everything
back together again. The /EX switch is specified like this:
LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC.LIB /EX
A packed program will require less disk space, however it of
course requires the same amount of memory when it is run.
95
DiaLogic
Adding to the DIALOGIC Quick Library
We have provided you with the needed Quick Library file to allow
operation of DIALOGIC.BAS when in the environment. This Quick
Library contains the assembler routines on which DiaLogic
depends. However, you may need to add other routines so that
they too are available in the QuickBASIC environment. For
example, you may need to combine assembler or BASIC routines from
QuickPak Professional with DIALOGIC.QLB.
Quick Libraries are created with the version of LINK current with
or subsequent to the release of QuickBASIC version 4. Microsoft
has documented many of the capabilities of LINK in the QuickBASIC
manuals, though there are additional useful features with which
you should become familiar.
Normally, LINK expects a list of object file names to be
specified for inclusion in the Quick Library being built. But
you may also combine one or more entire .LIB libraries as well.
(A .LIB file simply contains one or more .OBJ modules in a single
file.) This feature is particularly useful if you need to
combine several .LIB library files into a single Quick Library.
To create a new Quick Library comprised of one or more .LIB and
.OBJ files, invoke LINK like this:
LINK /Q LIBFILE1.LIB LIBFILE2.LIB OBJ1 OBJ2,LIBNAME,NUL,BQLB45
The /Q option tells LINK that it is to create a Quick Library
rather than an .EXE file. LIBFILE1.LIB and LIBFILE2.LIB are the
library files being incorporated into the new Quick Library, and
OBJ1 and OBJ2 are object modules. Of course, you can mix and
match library and object files in any order you would like.
The .LIB extension is very important, because without it LINK
would be looking for files with an .OBJ extension. Notice that
an extension is not needed for the object files.
96
Creating Standalone Programs
The LIBNAME parameter is the name that you want to use for the
new Quick Library being built. Without the LIBNAME parameter,
LINK will default to the same name as the first .LIB or .OBJ file
in the list. In the example above, the file generated would have
been named the same as LIBFILE1.LIB if LIBNAME had been omitted.
In that case, though, the comma ``place holder'' is still
required:
LINK /Q LIBNAME1.LIB LIBNAME2.LIB OBJ1 OBJ2,,NUL,BQLB45
The NUL parameter prevents LINK from generating a list file, and
BQLB45.LIB is a special library supplied with QuickBASIC.
BQLB45.LIB, for example, has nothing to do with Dialog Software,
and is required for making any Quick Library that will be used
with BASIC. Note that BQLB45 may have a slightly different name,
depending on the version of QuickBASIC.
One final important note about making Quick Libraries is the /SEG
option. When many separate object modules are being combined,
the number of code and data segments may exceed the LINK's
default maximum of 128. When we create Quick Libraries we always
tell LINK to allow for up to 256 segments like this:
LINK /Q /SEG:256 LIBFILE.LIB,,NUL,BQLB45
97
DiaLogic
PART VI
ADVANCED TOPICS
Advanced Topics
Creating advanced dialog boxes is a matter of being more
acquainted with the use of the Action% argument in the DiaLogic
call. While most advanced uses of dialog boxes, such as stacking
and multi-tasking, are presented in the commented DEMO.BAS
program, you may find the following explanations and additional
examples to be very helpful. You should understand that due to
the power and flexibility of DiaLogic, the examples which follow
are by no means exhaustive, nor do they represent a ``best way''.
You will benefit most by carefully studying our example programs
for a conceptual understanding, and by reading the discussions
below. After doing this the best teacher will be the experience
you gain by experimenting on your own.
This chapter consists of four sections. In the first section we
will offer some guidance on how to choose the type of dialog box
you may need to generate. In the second section we will discuss
single-tasking dialog boxes only, beginning with a review of the
simplest (i.e., Action-0) dialog box similar to the one presented
in Part IV: Generating a Dialog Box. In the third section we
will discuss multi-tasking dialog boxes which, by definition, are
called in a polled mode. And last, in the fourth section we will
discuss ways to stack dialog boxes on top of one another.
Note:
In this section, we introduce Action values as they are
needed. For an overview of all Action% values please
refer to page 82.
All examples in this section use the fully-commented BASIC
programs on the distribution diskette which begin with the word
``EXAMPLE'' and have an appended number to designate to which
example it corresponds. Thus, EXAMPLE1.BAS contains the sample
program for our first discussion below. Please note that in
order to load the example files properly, QuickBASIC should be
started using the DiaLogic Quick Library which appears on your
distribution diskette. Further, all programs should be loaded
using the QuickBASIC File Open pull-down menu option.
101
DiaLogic
This section uses two dialog box templates: FIND.DB, which is
exactly like the dialog box used by QuickBASIC 4.5, and a help
dialog box called FINDH.DB. Since these templates are
conceptually similar to the ones you created in Part IV: Creating
a Template, this section makes an attempt to resume and complete
our previous discussions.
Choosing a Dialog Box Type
In general you should use single-tasking dialog boxes since they
are easiest to implement and are slightly faster since polling
does not occur. Multi-tasking dialog boxes should be used only
when a background process must execute while the dialog box is in
use. Examples of necessary background processes might be
updating the time on the screen or capturing input from a modem.
If you choose a single-tasking dialog box you should consider
whether you will need to stack dialog boxes. Generally, stacked
dialog boxes are used only when a dialog box requests help or
generates an error. Still, the choice to stack dialog boxes is
based more on aesthetics than anything else. Since stacked
dialog boxes appear to be on top of one another (please see the
discussion about Level on page 78), it makes sense that the
topmost dialog box should convey information about the dialog box
directly beneath it. Indeed, the convention is to generate an
overlaying dialog only when the new dialog box will be presenting
information related to the dialog box which generated it.
If you choose to generate a multi-tasking dialog box then you
have the added ability to modify a dialog box while it is being
used. This feature is useful when certain options on a dialog
box must be immediately updated based on selections made. Multi-
tasking dialog boxes are polled from the calling program,
therefore, any information entered by the user may be examined
after each polling cycle.
Please carefully review all of our examples. Once you understand
the various uses of Action, you will realize that DiaLogic can
support any kind of dialog box you will need to implement.
102
Advanced Topics
Single-Tasking Dialog Boxes
As we mentioned earlier, single-tasking dialog boxes require that
full control be passed to DiaLogic while a dialog box is being
used.
Action 0 provides the most straightforward "no-nonsense"
interface to DiaLogic. In fact, when Action is 0 the program
control will remain with DiaLogic until the dialog box is closed
by the user. At that point the dialog box will be removed and
the screen will be restored to its pre-dialog box state.
The use of Action 0 also will not inhibit the ability to
effectively communicate with the user. In fact, once DiaLogic
removes a dialog box it is prepared to generate another one.
This makes it possible to immediately follow one dialog box with
another. Our first example program, EXAMPLE1.BAS, demonstrates
this. The user is presented with a Find dialog box. If the
<Help> command button is used, then the dialog box is removed
from the screen and control is passed back to the calling program
(EXAMPLE1.BAS, in this instance). After, the calling program
will generate a new dialog box which displays a help message in a
list box. When the user closes this dialog box (by pushing <OK>)
the calling program will again generate the Find dialog box.
This cycle occurs in a DO loop and can continue each time <Help>
is pushed. Remember that since all Action-0 dialog boxes are
generated at Level 1 there is little memory that needs to be
dedicated to the DB() array. When <OK> or <Cancel> is finally
chosen the calling program may then resume processing.
EXAMPLE1.BAS demonstrates how an Action-0 dialog box can preserve
its settings. In this instance, the user may have entered a
search string before feeling the need to request help. Suppose
that this search string was a complex formula, and required much
careful typing. It would be very unfair to the user if DiaLogic
cleared the string whenever a simple request for help was made.
An elegant way to use Action-0 dialog boxes is to preserve
selected values for later, so that preferred options are
automatically selected for the user when the dialog box is next
generated.
103
DiaLogic
One technique for preserving dialog box settings makes use of
variable names in the dialog box template. For instance, the
Find What text box template definition appears like this:
DB(Level%, 2).Code = 2
DB(Level%, 2).Y = 2
DB(Level%, 2).X = 14
DB(Level%, 2).Wdth = 44
DB(Level%, 2).BorderType = 1
DB(Level%, 2).PrimaryColor = 112
DB(Level%, 2).WindowColor = 112
DB(Level%, 2).SelectedColor = 7
DB(Level%, 2).TextY = 3
DB(Level%, 2).TextX = 3
DB(Level%, 2).Text = "~Find What:"
DB(Level%, 2).TextColor = 112
DB(Level%, 2).KeyColor = 127
DB(Level%, 2).TextString = Search$
DB(Level%, 2).ItemLength = 50
104
Advanced Topics
Notice that the default edit string is assigned to Search$ in the
template! An include file may contain variable names since
QuickBASIC compiles it along with the rest of the program.
EXAMPLE1.BAS preserves all the Find dialog box selections as soon
as it returns from the call using the following statements:
.
.
.
'Search$ holds our
' search string
Search$ = MID$(DB(Level%, 2).TextString, 1, _
DB(Level%, 2).NumberOne)
MatchCase = DB(Level%, 3).Default
'-1 if Match Case is checked
WholeWord = DB(Level%, 4).Default
'-1 if Whole Words is checked
SearchType = DB(Level%, 5).Default
'1 for Active Window, 2 for
' Current Module, or 3
' for All Modules
Each variable (i.e., Search$, MatchCase, WholeWord, and
SearchType) appears in the default assignments of the FIND.DB
dialog box template.
105
DiaLogic
Another useful technique is to use variable names for the
command-button key. Consider the <Help> command button template
structure for the Find dialog box used by EXAMPLE1.BAS:
DB(Level%, 11).Code = 7
DB(Level%, 11).Y = 11
DB(Level%, 11).X = 43
DB(Level%, 11).Text = "~Help"
DB(Level%, 11).PrimaryColor = 112
DB(Level%, 11).WindowColor = 112
DB(Level%, 11).SelectedColor = 7
DB(Level%, 11).KeyColor = 127
DB(Level%, 11).SecondaryColor = 127
DB(Level%, 11).TextString = Help$
Recall that the string assigned to DB().TextString for a command
button is returned in Ky$ whenever that command button is pushed.
Thus, if the <Help> is active when the dialog box is closed, then
Ky$ will have the string value of Help$. This is possible since
the very beginning of EXAMPLE1.BAS (before the template include
statements) defines several variables as such:
Esc$ = CHR$(27)
Help$ = CHR$(0) + CHR$(59)
OK$ = CHR$(13)
The Help$ has the same string value as the <F1> key; ESC$ is the
same as <Esc>; and OK$ is the same as <Enter>.
Knowing which command button was active will let us know if we
should ignore the dialog box (<Cancel>), generate a help message
(<Help>) or accept the dialog box information and continue
processing (<OK>). This decision process occurs in a SELECT CASE
statement.
106
Advanced Topics
Multi-Tasking Dialog Boxes
Multi-tasking dialog boxes have the ability to be behave quite
normally even though they are being repeatedly called in a loop.
These dialog boxes are called initially with an Action of 1,
which displays a dialog box and returns to the calling program.
Subsequent calls are made using an Action of 3. The Action
remains 3 until input is received by the dialog box, at which
point the Action becomes 4. This allows the calling program to
react to the dialog box only when some dialog box activity has
occurred. This creates an efficient polling structure.
Note:
If the calling program wishes to terminate the polling
mode, then Action may be set to 7, and the dialog box
will resume execution in single-tasking mode as if it had
been generated with an Action of 6. Once the dialog box
is closed it must be removed from the screen using Action
5. Action 6 is discussed below.
EXAMPLE2.BAS provides a demonstration of a multi-tasking dialog
box. This program updates the time on the dialog box at a rate
which is fast enough to appear smooth. The dialog box is fully
able to accept input, both with the mouse or with the keyboard,
even though it is being polled. The core of the polling takes
place in a nested DO loop.
The innermost DO loop will keep calling DiaLogic until Action
becomes 4. Recall that Action 3 allows DiaLogic to return to a
calling program as soon as it checks for input. If input is
received, DiaLogic sets Action to 4. Action 4 is simply a signal
for the calling program that some input (either from the keyboard
or mouse) was received by DiaLogic.
107
DiaLogic
Once Action is 4, the calling program should first check the
command buttons in order to determine what to do next. In
EXAMPLE2.BAS we have provided some interesting ideas on how
multi-tasking dialog boxes may be used.
One aesthetic consideration of multi-tasking dialog boxes is the
cursor. The blinking hardware cursor will appear to ``flicker''
or ``dart around'' during some background processes. For this
reason, we suggest turning the cursor off before the background
process like this:
LOCATE , , 0
The cursor may be turned on again by this statement:
LOCATE , , 1
Note:
Although this example shows that the time (or any other
process) can be run alternately with DiaLogic, you should
be aware that a dialog box can be polled without doing
any background task. Thus, our time-update routine could
just as well be a series of REM statements. The
important point here is that using a dialog box in polled
mode offers a calling program the ability to dynamically
interact with a dialog box, effectively extending
DiaLogic's processing.
The <Help> command button in EXAMPLE2.BAS is displayed in blue to
make it different from other command buttons. While any color
will do, we have made <Help> different because no help is
available for this dialog box. If <Help> is selected, then an
error beep will be sounded, and the choice will be ignored.
108
Advanced Topics
While deactivating command button may not be something you would
wish to do, the technique alone demonstrates how the calling
program can participate in the logic involved when processing
user input.
The <OK> command button demonstrates how to update a dialog box
on-the-fly, that is, while it is being used. Thus, whenever <OK>
is selected, a special message appears in the text box, both
check boxes are checked, and choice 2 in the Search group box is
selected. This happens very quickly, and after the dialog box
remains fully-functional. This feature allows the calling
program to insure that certain options are checked or unchecked
based on what has been selected. Although EXAMPLE2.BAS checks
for which command button was pushed, it could have examined which
check box was selected before deciding to update the dialog box
elements. Your own experimentation will surely result in even
more creative ways to implement multi-tasking dialog boxes.
Stacked Dialog Boxes
Overview
The benefits to stacked dialog boxes are mainly aesthetics and a
desire to create a superior user interface. Our discussion of
stacked dialog boxes will use the term primary dialog box to
refer to the first dialog box that is generated, and secondary
dialog box to refer to the overlaying dialog box.
Note:
Although this section will focus on the use of two dialog
boxes only, DiaLogic can of course handle as many dialog
boxes as you wish. However, some variables in the
DiaLogic source program, DIALOGIC.BAS, will have to be
modified if you desire to stack more than two dialog
boxes on the screen. If this applies, please see
Appendix B: Modifying DIALOGIC.BAS.
109
DiaLogic
In order to stack dialog boxes the primary dialog box must be
generated in such a way that control will be passed back to the
calling program before the dialog box is removed from the screen
and before the decision to generate an overlaying dialog box is
made. In order to accomplish this, the primary dialog box must
be generated using an Action of 1 or 6. Recall that Action 1
generates a dialog box and returns immediately to the calling
program. Action 6, on the other hand, generates a dialog box and
waits for input, then it returns to the calling program. Both
Action 1 and Action 6 will keep the dialog box on the screen when
returning to the calling program.
The secondary dialog box is most often generated with an Action
of 0 simply because it is very rare and often undesirable to
stack more than 2 dialog boxes. However, if you wish to stack
dialog boxes to a Level greater than 2 then you may generate the
secondary dialog box just like the primary dialog box using
Actions 1 and 6 (please see the Note on the preceding page).
Once the secondary dialog box is removed from the screen the
underlying primary dialog box has to be re-activated. This is
easily accomplished with a single call to DiaLogic using Action
2, which will re-read the DB() array and update all text boxes,
list boxes, check boxes, and option buttons in the highest-Level
dialog box currently on the screen. After this, DiaLogic must be
called with Action 7 in order for DiaLogic to resume processing.
Action 7 behaves just like Action 6, and full control will remain
with DiaLogic until the dialog box is closed. At this point, the
dialog box remains on the screen, and the calling program can
decide what to do next. Like Action-1 and Action-6 dialog boxes,
when a dialog box is re-activated using Action 7, it must
ultimately be removed from the screen with a call to DiaLogic
using an Action of 5.
We will present two programs. The first, EXAMPLE3.BAS, discusses
how to stack single-tasking dialog boxes. The second,
EXAMPLE4.BAS, discusses how to stack multi-tasking dialog boxes.
110
Advanced Topics
Single-Tasking Stacked Dialog Boxes
EXAMPLE3.BAS shows a Find dialog box which is generated using
Action 6. This Action displays a dialog box and waits for input.
There are three command buttons on it: <OK>, <Cancel>, and
<Help>. If <OK> is pushed, the dialog box is removed from the
screen using Action 5 and is processed normally. If <Cancel> is
pushed, then the dialog box is removed from the screen, also
using Action 5, and the dialog box contents are ignored. If
<Help> is pushed then the Find dialog box remains on the screen.
At this point the calling program sets Level to 2 and defines the
secondary dialog box template. Then, DiaLogic is called with an
Action of 0. This will generate a help dialog box as the
secondary dialog box. When the Help dialog box is acknowledged
then it will be removed from the screen. In order to re-activate
the primary Find dialog box, DiaLogic must be called with an
Action of 2 followed by an Action of 7. The Find dialog box is
ultimately removed from the screen using Action 5.
Thus, to stack single-tasking dialog boxes, the primary one must
be generated with an Action of 6, which is identical to an Action
of 0 except the dialog box is not removed from the screen when it
is closed. Action 6 therefore allows DiaLogic to return to the
calling program while leaving a full dialog box on the screen.
When the time comes to remove the dialog box, DiaLogic must be
called with an Action of 5. This Action always removes the
dialog box with the highest Level from the screen.
Note:
Never remove a dialog box from the screen by using the
CLS (clear screen) BASIC statement, or any other
method. Avoiding the use of Action 5 in this way will
cause DiaLogic's internal pointers to be corrupted.
111
DiaLogic
Notice that in this example our program does not bother to check
anything about the dialog box if Action is not 4. This is
efficient, since no background time is wasted: this allows the
greatest portion of the computer time to be dedicated to
DiaLogic's processing.
Multi-Tasking Stacked Dialog Boxes
EXAMPLE4.BAS shows a Find dialog box which is generated using
Action 1. This Action displays a dialog box and immediately
returns to the calling program. At this point the calling
program can do anything it wishes before activating the dialog
box. One useful idea is to print information, such as the
current date, directly on the dialog box using a PRINT statement.
In other words, generating a dialog box with Action 1 allows the
calling program to embellish the dialog box with information
which is not defined in the template.
In EXAMPLE4.BAS, however, the Action is set to 3 and a DO loop
begins to execute. Since Action is three the call to DiaLogic
will return after the dialog box has been polled. The time is
printed on the dialog box to demonstrate multi-tasking. Then
EXAMPLE4.BAS checks to see if Action is 4. Recall that Action
becomes 4 only when the dialog box has received some input.
While Action remains 3 the IF statements are completely ignored.
As soon as Action becomes 4 the calling program checks to see if
a command button has been pushed. If <Help> is requested, then
the Help dialog box is generated by setting Level% to 2, defining
the template, and calling DiaLogic with an Action of 0. Thus,
the Help dialog box will be single-tasking, and will remove
itself from the primary Find dialog box as soon as it is closed.
Once Help is acknowledged, the primary Find dialog box is re-
activated by calling DiaLogic with an Action of 2 followed by an
Action of 3, since we wish to continue multi-tasking.
If <OK> is pushed, then the Find dialog box is removed from the
screen using Action 5, and the results are printed. If <Cancel>
is pushed then the dialog box is removed but the results are
ignored.
112
Advanced Topics
It should be clear that using Action the correct way will allow
many variations in the way DiaLogic is used. We wish to make
this product smaller, better, and more powerful with each new
release. If you have ideas for improvement, both in the program
or documentation, please let us know!
We hope you enjoy using DiaLogic.
113
DiaLogic
APPENDICES
DiaLogic
APPENDIX A
DIALOG BOX ELEMENTS
Appendix A: Dialog Box Elements
The Window
DB(Level, 1).Code = 1
Code for window.
DB(Level, 1).Y =
Y coordinate of upper-left corner.
DB(Level, 1).X =
X coordinate of upper-left corner.
DB(Level, 1).Height =
Height of window.
DB(Level, 1).Wdth =
Width of window.
DB(Level, 1).BorderType =
Border type. If negative then window will ``explode.''
DB(Level, 1).PrimaryColor =
Color of window border. If negative then the window will cast a
shadow.
DB(Level, 1).WindowColor =
Color of window. If negative then a horizontal line will be
drawn near the bottom of the dialog box.
DB(Level, 1).Text =
Optional centered title of the window.
DB(Level, 1).TextColor =
Color of window title.
DB(Level, 1).SecondaryColor =
Color of optional bottom horizonal line.
DB(Level, 1).NumberOne =
Number of screen lines. This number may be 25, 43, 50 or 60,
depending on the type of display adapter used. Default is 25.
A - 3
DiaLogic
Text Box
DB().Code = 2
Code for text box.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Wdth =
Width of text box.
DB().BorderType =
Border type.
DB().PrimaryColor =
Border color.
DB().WindowColor =
Color of unselected text inside the text box window.
DB().SelectedColor =
Color of selected text.
DB().TextY =
Y coordinate for text box label.
DB().TextX =
X coordinate for text box label.
DB().Text =
Text box label. May contain a tilde for Alt-key operation.
DB().TextColor =
Color of text box label.
DB().KeyColor =
Color of the Alt-key in the text box label.
DB().TextString =
Text box default edit string.
DB().ItemLength =
Maximum number of characters which may be entered.
DB().NumberOne =
Length of the returned string (held by DB().TextString).
A - 4
Appendix A: Dialog Box Elements
List Box
DB().Code = 3
Code for list box.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Height =
No. items vertically within the list box borders.
DB().Wdth =
No. items horizontally within the list box borders.
DB().WindowColor =
Color of ``empty'' space within list box borders.
DB().PrimaryColor =
Color of primary list box items.
DB().SecondaryColor =
Color of secondary list box items.
DB().SelectedColor =
Color of selected items.
DB().StarColor =
Color of scroll bars.
DB().ItemLength =
Length of a single list box item.
DB().KeyColor =
Number of spaces between list box columns.
DB().BorderType =
Scroll bars: 0=none; 1=bottom; 2=side; 3=both.
DB().Link =
Link code. 0=none; >0=text-box; <0=sentence.
DB().TextY =
Y coordinate for sentence links.
DB().TextX =
X coordinate for sentence links.
DB().TextColor =
Color of sentence links.
DB().NumberOne =
LB() starting element.
DB().NumberTwo =
LB() ending element.
DB().Default =
The LB() array element number to be selected by default.
A - 5
DiaLogic
Check Box
DB().Code = 4
Code for check box.
DB().Y =
Y coordinate of check box's left bracket.
DB().X =
X coordinate of check box's left bracket.
DB().PrimaryColor =
Color when unselected.
DB().SelectedColor =
Color when selected.
DB().TextY =
Y coordinate for check box label.
DB().TextX =
X coordinate for check box label.
DB().Text =
Check box label. May contain a tilde for Alt-key
function.
DB().TextColor =
Color of check box label.
DB().KeyColor =
Color of the alt-key in the check box label.
DB().StarColor =
Toggle star color.
DB().Default =
Default status of check box. 0=off; -1=on.
A - 6
Appendix A: Dialog Box Elements
Option Buttons
DB().Code = 5
Code for option buttons.
DB().NumberOne =
Number of option buttons in this cluster.
DB().Default =
Default option button.
DB().TextString =
Location string holding coordinates for each button in
the cluster.
DB().WindowColor =
Color of button's parentheses.
DB().SelectedColor =
Color (of centered dot) when selected.
DB().StarColor =
Color of toggle star.
A - 7
DiaLogic
Smart Label
DB().Code = 6
Code for smart label.
DB().Y =
Y coordinate of smart label text.
DB().X =
X coordinate of smart label text.
DB().Text =
Smart label text. May contain a tilde for alt-key function.
DB().TextColor =
Color of smart label.
DB().KeyColor =
Color of the alt-key in the smart label text.
DB().Link =
Sequence of the dialog box element which is to be an
Alt-key link to this smart label.
DB().NumberOne =
Button number for a linked option button cluster.
A - 8
Appendix A: Dialog Box Elements
Command Button
DB().Code = 7
Code for command button.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Text =
Command button text. May contain a tilde for Alt-key function.
DB().PrimaryColor =
Color of angle brackets when command button is inactive.
DB().SecondaryColor =
Color of angle brackets when command button is active.
DB().WindowColor =
Color of text between angle brackets when unselected.
DB().SelectedColor =
Color of command button when selected.
DB().KeyColor =
Color of the Alt-key character.
DB().Default =
Default status: -1=on; 0=off.
DB().TextString =
Sets Ky$ return value for this command button. This should be
a valid key string, such as CHR$(27) for <Esc>.
A - 9
DiaLogic
Group Box
DB().Code = 8
Code for group box.
DB().Y =
Y coordinate of upper-left corner.
DB().X =
X coordinate of upper-left corner.
DB().Height =
Height of box.
DB().Wdth =
Width of box.
DB().BorderType =
Border type.
DB().SecondaryColor =
Color of group box border.
DB().Text =
Text for the top center of group box.
DB().TextColor =
Color of the text label.
A - 10
DiaLogic
APPENDIX B
MODIFYING DIALOGIC.BAS
Appendix B: Modifying DIALOGIC.BAS
Note:
DIALOGIC.BAS is extremely complex and should you wish to
alter it we ask that you preserve an original copy as a
backup. If you are trying to correct what you believe
to be a bug, or if you have a suggestion for an improve-
ment, please contact us. We will try to quickly
correct bugs and provide you with a patch or update,
and we will often incorporate ideas for improvement in
a future release.
We suggest two ways in which DIALOGIC may be safely modified.
The first concentrates on reducing the size of the DIALOGIC.BAS
module; the second discusses changing default constants.
Reducing the Size
The most desirable reduction will result when the mouse routines
are removed. While you may of course delete mouse-related code,
we suggest using the REM statement.
Two subprograms contain most of the mouse code. The first,
MouseInput, may be fully omitted. The second subprogram is
CentralInput, and we have clearly marked the begin and
end portion of the mouse-related code. To find this easily,
simply search for a block of ``MMMMM'' lines. The code
between the first and second block may be completely removed.
These omissions will remove the most mouse-related instructions
and will reduce the size of the DIALOGIC module as a result.
An additional reduction in size may be achieved if most of
the list-box related code is removed. Just like the mouse, there
are two subprograms which contain the majority of list-box code.
The first is LBox, and this entire subprogram may be REM'd
between the blocks of ``LLLLL'' characters. A similar operation
between ``LLLLL'' blocks should be conducted in the
CentralInput subprogram.
Changing Default Constants
A few constants are defined at the main module level of
DIALOGIC.BAS. You may change the value of any of these
constants in accordance with the instructions below:
Variable What it means & how to change it
AltKeyClose% If -1 then a dialog box will close
whenever the input focus is transferred to a
command button using an Alt-key. If 0 then
a dialog box will not close automatically
but will wait for <Enter>. The default is
-1.
AutoRepeat! Holds the auto-repeat delay when the mouse
is used to scroll text box or list box
contents. The default is 0.09 seconds.
JustPressedPause! Holds the delay, in seconds, before
auto-repeat is enabled when a mouse is used.
The default is 0.3 seconds.
MickeyDelay! Holds the acceleration delay when the mouse
is used to scroll text box or list
box contents. The default is 0.01 seconds.
ShowAltKey% If 0 then Alt-keys will not be revealed
until an <Alt> key is pressed. If -1, then
all Alt-keys will be shown when the dialog
box first opens. The default is 0.
MaxDialog% Sets the greatest Level number which
DiaLogic can use. The default, 2, means
that no more than 2 dialog boxes may be on
the screen at one time. The value of
MaxDialog% must always be equal to or
greater than the highest Level used by the
calling program.
MaxDBE% Sets the greatest DBE number. The
default, 20, means that a single dialog
box can have no more than 20 dialog box
elements, including the window. The value
of MaxDBE% must always be equal to or
greater than the highest Sequence used by the
calling program.
B - 3
DiaLogic
APPENDIX C
TROUBLESHOOTING
Appendix C: Troubleshooting
DiaLogic has been tested with many dialog box templates and we
are confident that it can handle most any design. In general, if
there is a problem in the way that a particular dialog box
element, such as a list box, is behaving then we must strongly
suggest that you examine its dialog box template. Often problems
arise simply because a wrong link number was specified. Other
times a value is out-of-range or used improperly.
Nevertheless, two brief sections are presented: Appearance
Problems and Operational Problems. We hope some of our tips
assist you if you encounter difficulty.
Appearance Problems
Some dialog box elements are off the screen, are not centered, or
are missing.
Check the template. Make sure that the Sequence of the
elements in the DB() array does not skip or repeat any
numbers. Check that the X and Y coordinates for the
dialog box elements are used properly. Remember that
these coordinates are upper-left offsets from the dialog
box window and not from the screen. Make sure that
foreground colors are not the same as background colors.
This will render an item invisible. Make sure that the
screen size is properly specified in the window definition.
List box items and/or their descriptions are not formatted
correctly.
Check both the link code used and insure that the strings
assigned to the LB() array are properly specified.
Out of memory occurs when the calling program attempts to
generate a dialog box.
This will happen if the code segment for the calling
program becomes large enough that DiaLogic must use the
far heap for its arrays. This problem is usually solved if
all arrays are dynamic and the /AH (huge array) switch is
used when compiling both DIALOGIC.BAS and the modules which
make calls to it.
C - 3
DiaLogic
Functional Problems
The mouse does not work yet the mouse is plugged into the
computer.
Check that the mouse driver is being loaded. Usually the
driver is specified as a .COM file in AUTOEXEC.BAT or as
a .SYS device driver in CONFIG.SYS.
Be sure to use the DiaLogic assembler routines InitMouse,
ShowCursor, and TextCursor. If TextCursor is used be
sure that colors are chosen properly.
The dialog box is displayed but then ``hangs''.
Insure that the last template assignment sets DB().Code
to 0. Make sure that the DB() and LB() arrays are
properly dimensioned.
Check your include file for the presence of the
right-arrow symbol. This symbol is the same as the DOS
end-of-file character (ASCII 26), and cannot be used as a
literal in an include file. Use CHR$(26) instead.
Ky$ returns wrong information about which command button was
pushed.
This problem occurs when DB().TextString is either
assigned incorrectly for a command buttons or when two
command buttons have the same DB().TextString defined.
C - 4
DiaLogic
APPENDIX D
COLOR CHART
Appendix D: Color Chart
Color Chart
BACKGROUND
Black Blue Green Cyan Red Magenta Brown White
Black 0 16 32 48 64 80 96 112
Blue 1 17 33 49 65 81 97 113
Green 2 18 34 50 66 82 98 114
F Cyan 3 19 35 51 67 83 99 115
O Red 4 20 36 52 68 84 100 116
R Magenta 5 21 37 53 69 85 101 117
E Brown 6 22 38 54 70 86 102 118
G White 7 23 39 55 71 87 103 119
R Br Black 8 24 40 56 72 88 104 120
O Br Blue 9 25 41 57 73 89 105 121
U Br Green 10 26 42 58 74 90 106 122
N Br Cyan 11 27 43 59 75 91 107 123
D Br Red 12 28 44 60 76 92 108 124
Br Magenta 13 29 45 61 77 93 109 125
Br Brown 14 30 46 62 78 94 110 126
Br White 15 31 47 63 79 95 111 127
D - 3
DiaLogic
APPENDIX E
ASCII CHARACTER CHARTS
Appendix E: ASCII
Character Charts
Conventional ASCII Character Codes
000 (nul) 016 ^P (dle) 032 sp 048 0 064 @ 080 P 096 ` 112 p
001 ^A (soh) 017 ^Q (dc1) 033 ! 049 1 065 A 081 Q 097 a 113 q
002 ^B (stx) 018 ^R (dc2) 034 " 050 2 066 B 082 R 098 b 114 r
003 ^C (etx) 019 ^S (dc3) 035 # 051 3 067 C 083 S 099 c 115 s
004 ^D (eot) 020 ^T (dc4) 036 $ 052 4 068 D 084 T 100 d 116 t
005 ^E (enq) 021 ^U (nak) 037 % 053 5 069 E 085 U 101 e 117 u
006 ^F (ack) 022 ^V (syn) 038 & 054 6 070 F 086 V 102 f 118 v
007 ^G (bel) 023 ^W (etb) 039 ' 055 7 071 G 087 W 103 g 119 w
008 ^H (bs) 024 ^X (can) 040 ( 056 8 072 H 088 X 104 h 120 x
009 (tab) 025 ^Y (em) 041 ) 057 9 073 I 089 Y 105 i 121 y
010 (lf) 026 ^Z (eof) 042 * 058 : 074 J 090 Z 106 j 122 z
011 (vt) 027 ^[ (esc) 043 + 059 ; 075 K 091 [ 107 k 123 {
012 (np) 028 ^\ (fs) 044 , 060 < 076 L 092 \ 108 l 124 |
013 (cr) 029 ^] (gs) 045 - 061 = 077 M 093 ] 109 m 125 }
014 ^N (so) 030 ^^ (rs) 046 . 062 > 078 N 094 ^ 110 n 126 ~
015 ^O (si) 031 ^_ (us) 047 / 063 ? 079 O 095 _ 111 o 127
Extended ASCII Chart (character codes 128 - 255)
128 144 160 176 192 208 224 240
129 145 161 177 193 209 225 241
130 146 162 178 194 210 226 242
131 147 163 179 195 211 227 243
132 148 164 180 196 212 228 244
133 149 165 181 197 213 229 245
134 150 166 182 198 214 230 246
135 151 167 183 199 215 231 247
136 152 168 184 200 216 232 248
137 153 169 185 201 217 233 249
138 154 170 186 202 218 234 250
139 155 171 187 203 219 235 251
140 156 172 188 204 220 236 252
141 157 173 189 205 221 237 253
142 158 174 190 206 222 238 254
143 159 175 191 207 223 239 255
Notes:
127 triangular symbol
152 "y" with umlaut
231 upsilon
251 check mark
E - 3
DiaLogic
GLOSSARY
Glossary
alt-key:
A character from 0 to 9 or from ``A'' to ``Z'' which is
pressed while the <Alt> key is held down. Alt-keys
typically transfer the input focus and provide direct
access to a dialog box element without having to use the
mouse.
active command button:
The command button which has its angle brackets
highlighted.
check box:
The dialog box element which allows an option to be
toggled on or off.
click:
A mouse operation where the mouse cursor is placed
``over'' a portion of the screen and a mouse button is
quickly pressed and released.
command button:
The dialog box element which returns control to the
calling program when selected. Typical command buttons are
<OK> and <Cancel>.
directional keys:
Usually considered to be any key which moves the cursor.
These keys include the right, left, up, and down arrows;
<PgUp>, <PgDn>; and <Home> and <End> in some
circumstances.
DBE:
See dialog box element.
dialog box:
An aesthetic data-entry screen which, as a popup window,
can appear and disappear without disturbing the screen
contents. Dialog boxes provide a standard interface
and are fully compatible with a mouse.
dialog box element:
Any of the eight building blocks of a dialog box: the
window, text box, list box, check box, option buttons,
smart label, command button, and group box.
double-click:
A mouse operation where the mouse cursor is placed``over'' a
portion of the screen and a mouse button is pressed and
released two times in rapid succession.
drag:
A mouse operation which describes holding down a mouse
button while moving the mouse cursor.
group box:
The dialog box element which frames regions of the dialog
box.
Glossary - 3
DiaLogic
input focus:
The current position of the cursor on the dialog box.
The input focus rests on the dialog box element which is
prepared to accept input.
level:
Refers to a dialog box template in the DB() array. The
Level is the first subscript of this array.
link:
For list boxes: provides a way to place a list box item
somewhere else on the dialog box. For smart labels:
provides a way to associate an Alt-key with a dialog box
element.
list box:
The dialog box element which presents a scrollable list
of items.
option buttons:
The dialog box element which allows one option from a
group to be selected.
polling:
A method of calling a program (a function or subroutine)
repeatedly in a loop. Polling can simulate multi-tasking
since more than one process may be executed in turn while in
the loop.
primary dialog box:
The dialog box which first appears on the screen.
scroll:
An operation, usually mediated by the directional keys on
the keyboard or by dragging the mouse, which shifts text in
a text box or list box.
scroll bar:
An optional list box component which contains a moving
pointer indicating the relative amount of information
remaining on either side of the cursor. Scroll bars have
arrow symbols which may be clicked on with the mouse to move
the cursor one line at a time within the list box. The
space between the scroll bar pointer and the arrow symbols
may be clicked on in order to scroll several lines at
one time. Scroll bars may appear on the right or bottom
border of a list box.
scroll bar pointer:
A dark block which appears on an optional scroll bar once a
list box is accessed. The pointer moves along the scroll
bar as list box contents are scrolled. The pointer may be
repositioned by dragging it with the mouse.
Glossary - 4
Glossary
secondary dialog box:
A dialog box which is stacked on an existing primary
dialog box.
select:
Usually refers to text which is highlighted in
preparation for a delete or copy operation but also refers
to thechoice of a particular option.
Sequence:
The order in which the dialog box elements appear in the
DB() array. The Sequence is the second subscript in the
DB() array.
smart label:
The dialog box element which places text anywhere on the
dialog box and may also form Alt-key links to other dialog
box elements.
stacked dialog boxes:
Two or more dialog boxes which are displayed on the screen
simultaneously and appear to be on top of one another.
text box:
The dialog box element which accepts text.